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USING THIS PUBLICATION 



This publication describes the use of VSAM (Virtual Storage Access 
Method), an access method of OS/VS (Operating System/ Virtual Storage). It 
is intended for Assembler language programmers who intend to use VSAM 
macro instructions to process data and for higher-level language programmers 
who may want to use ISAM programs to process data. The publication has 
the following major divisions: 

• "Introduction," which introduces basic VSAM concepts that the reader 
needs in order to use VSAM. 

• "Opening and Closing a Data Set," which describes job control language 
and the OPEN and CLOSE macros. 

• "Control Block Macros," which describes VSAM macros used to construct 
the control blocks required to open and use data sets and exit routines, and 
to modify, test, and display fields in control blocks. 

• "Request Macros," which describes macros used to retrieve, store, update, 
and erase records, and to suspend processing and terminate requests. 

• "Using ISAM Programming with VSAM," which describes how data sets 
can be converted to VSAM's format and can be processed using an ISAM 
processing program. 

• "User-Written Exit Routines," which describes how to write the exit 
routines that can be used with VSAM. 

• "Appendix A: Summary of Macros," which summarizes, for ease of 
reference, the format of the macros used to communicate with VSAM. 

• "Appendix B: List, Execute, and Generate Forms of GENCB, MODCB, 
SHOWCB, and TESTCB," which explains how to code reentrant programs 
with the macros that generate, modify, test, and display control blocks at 
execution. 

• "Appendix C: Operand Notation for GENCB, MODCB, SHOWCB, and 
TESTCB," which gives all of the ways of coding operands in the macros 
that generate, modify, test, and display control blocks at program 
execution time. 

• "Glossary," which defines VSAM terms. 

• "Index," which is a subject index to this publication. 



Conventions Used in the Publication 



The conventions used in this publication for writing the macro and JCL 
statements indicate whether an operand is optional, how to specify the value 
for an operand, and how to punctuate a macro or statement. The conventions 
are: 

• Expressions enclosed in brackets, [ ], are optional. 

• Items separated by an OR sign, | , and enclosed in braces, {}, are 
alternatives, only one of which may be specified. 

• An underlined item, item , is the default when you don't specify anything 
for an operand. 

• Ellipses, ..., indicate that you may repeat the preceding item. 
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Capitalized BOLD expressions, parentheses, commas, and equal signs must 
be entered as shown, except that, unless otherwise noted, parentheses 
aren't required if you specify only one item. 

Lowercase italic expressions are variables for which you may specify one 
of a number of expressions. 



VSAM and Access Method Services Publications 



The VSAM and Access Method Services libraries have been revised and 
expanded. Books listed below that are designated OS/VS I apply only to 
Release 4 of OS/VS1. Books designated OS/VS2 apply only to Release 3 of 
OS/VS2. Four new books designated OS/ VS2 Independent Component 
apply only to the release of VSAM as an independent component for use with 
Release 3 of OS/VS2. The shared book applies to OS/VS1, OS/VS2, and 
the independent component. 

This publication makes frequent references to the VSAM and Access Method 
Services publications. Rather than list all the titles at each reference point, the 
text will refer to the appropriate publication for the particular subject. 

The VSAM and Access Method Services publications are: 

• OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications, GC26-3819, which provides information about advanced 
applications of VSAM. The topics, which do not apply to make normal use 
of VSAM, include: gaining access to control intervals; I/O buffering; 
constructing parameter lists for the macros that generate, modify, and 
examine control blocks at execution; processing the index as data; sharing 
resources; and displaying fields of the catalog. 

• OS/VS1 Access Method Services, GC26-3840, OS/VS2 Access Method 
Services, GC26-3841, and OS/VS 2 Independent Component: Access 
Method Services, GC26-3843, which contain a complete description of 
the commands that are used to copy, print, and load data sets. They also 
describe the relationships among components, the structure of components, 
the use of the catalog, and Access Method Services commands that are 
used to define and delete data sets, list catalog entries, and move data sets 
from one operating system to another. These publications are directed to 
the person responsible for establishing and maintaining data sets in an 
installation. 

• OS/VS1 Access Method Services Logic, SY35-0008, OS/VS2 Access 
Method Services Logic, SY35-0010, and OS/VS2 Independent 
Component: Access Method Services Logic, SY26-3 845, which describe 
the internal logic of Access Method Services. 

• OS/VS1 Virtual Storage Access Method (VSAM) Logic, SY26-3841, 
which describes the internal logic of VSAM and of VSAM catalog 
management. 

• OS/VS2 Catalog Management Logic, SY26-3826, and OS/VS2 
Independent Component: Catalog Management Logic, SY26-3847, which 
describe the internal logic of VSAM catalog management. 

• OS/VS2 Virtual Storage Access Method (VSAM) Logic, SY26-3825, 
and OS/VS2 Independent Component: Virtual Storage Access Method 
(VSAM) Logic, SY26-3846, which describe the internal logic of VSAM, 
excluding VSAM catalog management. 
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Other Required Publications 



Related Publications 



The reader also needs to be familiar with some of the information presented 
in the following publications: 

• OS/VS Data Management Services Guide, GC26-3783, which presents 
basic concepts such as access method, direct-access storage, and the 
distinction between data-set organization and data-set processing. 

• OS/VS1 JCL Reference, GC24-5 099, which describes the JCL 
parameters for VS1 referred to in this publication. 

• OS/VS2 JCL, GC28-0692, which describes the JCL parameters for VS2 
referred to in this publication and describes dynamic allocation. 

• OS/VS2 System Programming Library: TSO, GC28-0629, which 
describes dynamic allocation. 



The reader may need to be f amiliar with some of the information presented in 
the following publications: 

• OS/VS 2 TSO Command Language Reference, GC28-0646, and 
OS/VS 2 TSO Terminal User's Guide, GC28-0645, which describe the 
TSO option of OS/VS2. 

Other publications referred to in this publication are: 

• OS/VS Checkpoint/ Restart, GC26-3784 

• OS/VS Message Library: VS1 System Messages, GC38-1001 

• OS/VS Message Library: VS2 System Messages, GC38-1002 

• OS/VS1 System Data Areas, SY28-0605 

• OS/VS2 Data Areas, SYB8-0606 
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SUMMARY OF AMENDMENTS 



Support for the new functions and data structures listed below has been 
added to this publication. The changes apply to Release 4 of OS/VS1. Users 
of Release 3 of OS/VS2 who plan to install the VSAM ICR (independent 
component release) on their system may use the new information for planning 
purposes only until the ICR is available. There are no significant changes for 
Release 3 of OS/VS2. 

The changes are: 

• Multiple indexes enable subsets of a single data set to be uniquely named, 
mounted, and processed. 

• Control interval size is no longer dependent upon the size of the largest 
record in a data set. Logical records may span control intervals within a 
single control area. 

• New options allow the sharing of I/O-related control blocks, channel 
programs, and buffers among several VSAM data sets open at the same 
time. Definitive descriptions of these options are published in OS/VS 
Virtual Storage Access Method (VSAM) Options for Advanced 
Applications. 

• Relative record data sets, a new type of data organization, permit the 
arithmetic calculation of the control interval containing a required record 
and of the record's position within the control interval. 

• GET-previous processing, a variation of sequential retrieval, returns the 
previous record (relative to current positioning) rather than the next 
record. 

• Improved control-interval processing is an optional performance 
enhancement that reduces the time and the number of CPU instructions 
required to gain access to a control interval. This processing is described in 
OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications. 

• Enhanced space reclamation makes it possible to reuse a single data set 
many times as a work file. 
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INTRODUCTION 



VSAM gives you both direct access to records in any order and sequential 
access to records that follow one another. You can identify a record for 
retrieval by its key (a unique value in a predefined field in the record), by its 
displacement from the beginning of the data set, or by its relative record 
number. These alternative types of access and access options enable you to 
design a program to suit your requirements for processing data. 

With VSAM you can build one or more alternate indexes over a single base 
data set, so that you need not keep multiple copies of the same information 
organized in different ways for different applications. In terms of access, an 
alternate index serves the same purpose as a primary index, but it does not 
account for space in the base data set and does not require unique keys. 

The Access Method Services commands are used to establish and maintain 
data sets and to copy and print data sets. These commands are described in 
the appropriate Access Method Services publication. 

The macros described in this publication include control block macros and 
request macros. The macros that are used to build control blocks, described in 
the chapter "Control Block Macros," are: 

• ACB, which is used to build an access-method control block at assembly 
time. 

• EXLST, which is used to build an exit list, which identifies available exit 
routines; the exit list is built at assembly time. 

• RPL, which is used to build a request parameter list at assembly time. 

• GENCB, which is used to build an access-method control block, an exit 
list, or a request parameter list at execution time. 

The macros that are used to modify, display, and test the contents of control 
blocks, also described in the chapter "Control Block Macros," are: 

• MODCB, which is used to modify an access-method control block, an exit 
list, or a request parameter list at execution time. 

• SHOWCB, which is used to display fields in an access-method control 
block, an exit list, or a request parameter list at execution time. 

• TESTCB, which is used to test the contents of fields in an access-method 
control block, an exit list, or a request parameter list at execution time. 

The macros used to store, retrieve, and erase records, to position VSAM in a 
data set, to suspend processing, and to terminate requests, described in the 
chapter "Request Macros," are: 

• GET, which is used to retrieve a record. 

• PUT, which is used to store a record. 

• ERASE, which is used to delete a record. 

• POINT, which is used to position VSAM at a record. 

• CHECK, which is used to suspend processing. 

• ENDREQ, which is used to terminate a request. 
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Types of Data Sets 



VSAM has key-sequenced, entry-sequenced, and relative record data sets. 
The primary difference among the three is the sequence in which data records 
are loaded into them. 

Records are loaded into a key-sequenced data set in key sequence: that is, in 
the order defined by the collating sequence of the contents of the key field in 
each of the records. Each record has a unique value, such as employee 
number or invoice number, in the key field. To determine where to insert a 
new record into the data set in key sequence, VSAM uses an index that pairs 
the key of a record with the record's location. 

Records are loaded into an entry-sequenced data set without respect to the 
contents of the records. Their sequence is determined by the order in which 
they are stored: their entry sequence. Each new record is stored after the last 
record in the data set. 

Records are loaded into a relative record data set in relative record number 
sequence, or you can supply the relative record number of each record and 
load them in random order. The data set may be described as a string of 
fixed-length slots, each of which is identified by a relative record number. 
When a new record is sequentially inserted, VSAM assigns the record either 
the next available relative record number in sequence or the number you 
supplied. 

When a data set is created, it is defined as a cluster. A cluster can be a 
key-sequenced data set, which consists of a data component and an index 
component, or it can be an entry-sequenced or relative record data set, which 
consists of only a data component. 

Any suballocated VSAM data set that does not have an alternate index and is 
not associated with key ranges may be used as a work file. That is, you can 
treat a filled data set as if it were empty and use it again and again, regardless 
of its old contents. 

All VSAM data sets are stored on direct-access storage devices. The records 
of a data set need not be stored in a continuous area of storage. From your 
point of view, the area is continuous, starting at address 0. VSAM addresses a 
point in the area by its displacement, in bytes, from 0, called its RBA 
(relative byte address). For example, the first record in a data set has RBA 0. 
The second record has an RBA equal to the length of the first record, and so 
on. RBAs are independent of a data set's being stored in nonadjacent areas 
on a volume or on several volumes. 

All VSAM data sets must be cataloged in a VSAM catalog. See the 
appropriate Access Method Services publication for a description of the 
catalog. 

The total space of a data set is considered to be divided into a continuous set 
of areas called control areas, which are further divided into control intervals. 
When you retrieve a record, the contents of the control interval in which it is 
stored are read in by VSAM. A control interval is thus the unit of data 
transmission between virtual and auxiliary storage. 

Key-sequenced and entry-sequenced data records whose lengths exceed 
control interval size may cross, or span, one or more control interval 
boundaries within a single control area. Such records are called spanned 
records. You must specify your intent to use spanned records when you 
define the data set. 
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Key-Sequenced Data Set 



Entry-Sequenced Data Set 



Relative Record Data Set 



A key-sequenced data set always includes an index, which is a mechanism for 
keeping track of records. An index relates key values to the relative locations 
of the records. 

The RBAs of records can change in a key-sequenced data set when records 
are added, deleted, shortened, or lengthened. 

A key-sequenced data set permits the full range of options for gaining access 
to data: keyed access (as well as addressed and control-interval access), 
insertion, deletion, and changing the length of a record. VSAM keeps track of 
records in a key-sequenced data set by key field, so that you need refer to a 
record only by its key field, and not in some location-dependent manner. 



The records in an entry-sequenced data set are in the order they are stored in 
time. That is, each new record is stored at the end; none is inserted. Records 
cannot be shortened, lengthened, or moved from one location to another. 
Records cannot be deleted, although they can be replaced with records of the 
same length. Once a record is added to an entry-sequenced data set, it stays 
there and keeps its original RBA. An entry-sequenced data set is essentially a 
sequential data set, but one whose records can be retrieved at random by 
direct access and can be updated. The search argument for direct retrieval is a 
record's RBA. 

An entry-sequenced data set is appropriate for applications that require no 
special ordering of data by the contents of a record. It is appropriate for a log 
or a journal, because its order corresponds to the chronology of events. To 
retrieve records randomly from an entry-sequenced data set, you must keep 
track of the records' RBAs and associate RBAs with the contents of records. 



A relative record data set has no index. It is a string of fixed-length slots, each 
of which is identified by a relative record number from 1 to n, where n is the 
maximum number of records that can be stored in the data set. Each record 
occupies a slot and is stored and retrieved by the relative record number of 
the slot. 

Records in a relative record data set are grouped together in control intervals, 
just as they are in a key-sequenced or an entry-sequenced data set. Each 
control interval contains the same number of slots. The size of each slot is the 
record length you specified when you defined the data set. 

Relative record data sets can be processed by key or by control interval. With 
keyed access, a relative record number is treated like a key. You can update 
records in place, delete records, and insert new records into empty slots. 
Control-interval processing is described in OS/VS Virtual Storage Access 
Method (VSAM) Options for Advanced Applications. 

You can use a relative record data set in much the same way you would use a 
BDAM (basic direct-access method) data set in which the data records are 
not ordered by their contents or their entry sequence. 

Figure 1 compares key-sequenced, entry-sequenced, and relative record data 
sets. 
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Key-Sequenced Data Set 



Entry-Sequenced Data Set 



Relative Record Data Set 



Records are in collating 
sequence by key field 

Access is by key through an 
index or by RBA 

May have one or more 
alternate indexes 

A record's RBA can change 



Records are in the order in 
which they are entered 

Access in by RBA 



Distributed free space is used 
for inserting records and 
changing their length in place 

Space given up by a deleted or 

shortened record is 

automatically reclaimed within a record of the same length 

a control interval 



Records are in relative 
record number order 

Access is by relative 
record number, which is 
treated like a key 

May not have alternate 
indexes 

A record's RBA cannot change A record's relative 

record number cannot 
change 

Space at the end of the data set Empty slots in the data 



May have one or more 
alternate indexes 



is used for adding records 

A record cannot be deleted, 
but you can reuse its space for 



Can have spanned records 



Can have spanned records 



set are used for adding 
records 

Space given up by a 
deleted record can be 
reused 

Cannot have spanned 
records 



Can be reused as a work 
file 



Can be reused as a work file Can be reused as a work file 
unless it has an alternate index unless it has an alternate index 

Figure 1. Comparison of Key-Sequenced, Entry-Sequenced, and Relative Record Data 
Sets 



Alternate Indexes 



Alternate-Index Clusters 



An alternate index provides a unique way to gain access to a related base data 
set, so that you need not keep multiple copies of the same information 
organized in different ways for different applications. For example, a payroll 
data set indexed by employee number can also be indexed by other fields such 
as employee name or department number. See the appropriate Access Method 
Services publication for a complete description of the commands used to 
define and build an alternate index. 

In terms of access, an alternate index performs the same function as the prime 
index of a key-sequenced data set. The data set over which the alternate 
index is built is the base cluster. It can be a key-sequenced or an 
entry-sequenced data set, but not a relative record or a reusable data set. 



The alternate index is an indexed cluster (the alternate-index cluster). It 
consists of an index component and a data component. The index component 
is identical in structure, format, and function to the prime index of a 
key-sequenced cluster. Likewise, the format of the alternate-index data 
component is identical to the base data set. Therefore, each entry in the 
sequence set of an alternate-index index component points to a control 
interval in the alternate-index data component. 

When building an alternate index, you can use as the alternate key any field 
in the base data set's records having a fixed length and a fixed position within 
each record. The alternate key must be in the first segment of a spanned 
record. For each alternate key, the data component of the alternate index 
contains a unique record. This record consists of the alternate key itself, 
followed by a pointer that is the prime key or RBA of the base data record 
that contains the alternate key. If more than one base data record contains 
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Alternate-Index Paths 



Alternate-Index Records 



System Header Information 



Alternate-Index Keys 



the alternate key then the alternate index record contains a pointer to each 
base data record. These duplicate, or nonunique keys are discussed in the 
section "Alternate-Index Keys." 



A path logically relates a base cluster and each of its alternate indexes. It 
provides a way to gain access to the base data through a specific alternate 
index. You define a path through Access Method Services. You must name it 
and you can give it a password, if you choose. The path name subsequently 
refers to the base cluster/ alternate-index pair. This means that when you 
refer to a path (by way of the OPEN macro, for example), both the base 
cluster and the alternate index are affected (opened). 



Each record in the data component of an alternate-index cluster is 
variable-length and contains system header information, the alternate key, 
and at least one pointer to a base data record. Data component records may 
span control intervals. 



System header information is fixed length and indicates: 

• Whether the alternate index record contains (1) prime keys or RBA 
pointers and (2) unique or nonunique keys 

• The length of each pointer 

• The length of the alternate key 



Unless the base data records span control intervals, any field in the base data 
records that has a fixed length and a fixed position within the record can be 
an alternate key. The alternate key must be in the first control interval of a 
spanned record. When an alternate index is created, the alternate keys are 
extracted from the base data records and ordered in collating sequence. If you 
build several alternate indexes over a base cluster, the alternate key fields of 
the different alternate indexes may overlap each other in the base data 
records. They can also overlap the prime key. 

Keys in the index component of an alternate index or of a key-sequenced 
base cluster are compressed- Keys in the data component of an alternate 
index are not compressed. That is, the entire key is represented in the 
alternate-index record. 

An alternate key may refer to more than one record in the base cluster. For 
example, if an alternate index is established by department number over a 
payroll data set organized by employee number, there will be several 
employees with the same department number. In other words, there will be 
several prime-key pointers (employee numbers) in the alternate-index record, 
one for each occurrence of the alternate key (department number) in the base 
data set. When multiple pointers are associated with a given alternate key 
value, the alternate key is said to be nonunique; if only one pointer is 
associated with the alternate key, it is unique. 
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Alternate-Index Pointers 



An alternate index uses prime keys if the base cluster is a key-sequenced data 
set and RBAs if the base cluster is an entry-sequenced data set. 

For a nonunique key, multiple pointers are associated with it. The pointers are 
ordered by their arrival times. That is, if a base data record is updated with a 
key change, or if a new record is inserted with the same alternate key value 
the new prime-key pointer is added to the end of the alternate-index record. 
In the case of a key change, the old pointer is deleted. 

A prime-key pointer has the same length as the prime key field of the base 
data record it points to. The maximum number of pointers that can be 
associated with a given alternate key is 32767, provided the maximum record 
length for spanned records is not exceeded. 



Alternate-Index Maintenance 



VSAM assumes alternate indexes are synchronized with the base cluster at all 
times and makes no synchronization checks during open processing; 
therefore, all structural changes made to a base cluster must be reflected in its 
alternate index or indexes. This maintenace is called index upgrade. You can 
maintain your alternate indexes or you can have VSAM maintain them. When 
the data set is defined with the UPGRADE attribute, VSAM will update the 
alternate index immediately when there is a change to the associated base 
data cluster. VSAM opens all the UPGRADE alternate indexes for a base 
cluster whenever the base cluster is opened for output and updates them if 
necessary. 

All the alternate indexes of a given base cluster that have the UPGRADE 
attribute belong to the upgrade set. The upgrade set is updated whenever a 
base data record is inserted, erased, or updated. The upgrading is part of a 
request and VSAM completes it before returning control to your program. If 
the upgrade fails because of a logical error, any modifications made to the 
base data or to another alternate index are nullified, and the request that 
caused the upgrade is rejected. 

If you specify NOUPGRADE when the data set is defined, you must provide 
a way to reflect insertions, deletions, and changes made to the base cluster in 
all associated alternate indexes. 
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Processing Options 



Types of Access 



Processing options include: 

• Types of access (keyed or addressed, and sequential, skip sequential, or 
direct) 

• Exit routines for special processing 

You can gain access to a data set with a mixture of options. For instance, if 
you were processing two portions of a data set concurrently, you might 
process one portion directly, asynchronously, using a work area; you might 
process the other sequentially, synchronously, in the I/O buffer. You could 
also alternate among the options to process a data set, switching, say, from 
direct to sequential access when you got to a point where you wanted to 
process records in ascending sequence. 

Processing options are specified in macros that generate control blocks when 
your program is assembled (ACB, EXLST, and RPL macros) or executed 
(GENCB macro). Each request for some action is associated with a request 
parameter list, which, in association with other control blocks, supplies the 
processing options for the request. See the chapter "Control Block Macros" 
for a description of the macro instructions and of the specification of the 
processing options. 

When you issue a request for a record, you can either wait until the request is 
completed to continue processing or go on with processing that is not 
dependent upon the first request while it is being carried out. Overlapping 
processing in this way can improve the performance of your job. 

VSAM can keep track concurrently of positions in a data set for many 
requests to a data set. You can thus process many portions of a data set 
during the same period of time. Such concurrent access may be used to 
increase throughput, where each request can be processed independently of 
the others. 

The standard request for access retrieves, stores, or deletes a single record. 
The standard request is described by a parameter list that indicates a single 
record. By chaining parameter lists together, you can retrieve or store many 
records with one request. You may not use chained parameter lists to update 
or delete records; you may use chained parameter lists only to retrieve records 
or to store new records. 



VSAM allows both sequential and direct access for each of its three types of 
data sets. Sequential access of a record depends on the position, with respect 
to the key, the relative byte address of the previously processed record, or the 
relative record number; direct access does not. During sequential access, 
records retrieved by key are in key sequence, records retrieved by RBA are in 
entry sequence, and records retrieved by relative record number are in 
relative record number sequence. To retrieve records after initial positioning, 
you don't need to specify a key, an RBA, or a relative record number. VSAM 
automatically retrieves or stores the next record in order, either next in key 
sequence, next in entry sequence, or next in relative record number sequence, 
depending on whether you're processing by key, by RBA, or by relative 
record number. 

With direct access, the retrieval or storage of a record is not dependent on the 
key, the RBA, or the relative record number of any previously retrieved 
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record. You must fully identify the record to be retrieved or stored by key, by 
RBA, or by relative record number. 

GET-previous processing is a variation of normal keyed or addressed 
sequential processing. Instead of retrieving or updating the next record in 
ascending sequence (relative to current positoning in the data set), 
GET-previous processing returns or updates the next record in descending 
sequence. You can select GET-previous processing for POINT, GET, PUT 
(update only), and ERASE operations. GET-previous processing is not 
permitted with control-interval or skip-sequential processing. 

VSAM allows a processing program or its subtasks to process a data set with 
multiple concurrent sequential and/or direct requests, each requiring that 
VSAM keep track of a position in the data set, with a single opening of the 
data set. Access can be to the same part or to different parts of a data set. 

You can use a suballocated VSAM data set as a work file, if the data set does 
not have an alternate index and is not associated with key ranges. That is, you 
can treat a filled data set as if it were empty and use it again and again 
regardless of its old contents. To reuse a data set, you need only to define it 
as reusable and specify that it be reset when you open it. 

For a key-sequenced data set the primary form of access is keyed access, 
using an index. For an entry-sequenced data set without an alternate index, 
the only forms of access are addressed (using the RBA determined for a 
record when it was stored in the data set) and control-interval access. For a 
relative record data set, the only forms of access are keyed (using the relative 
record number as the key) and control-interval access. Control-interval access 
is described in OS/VS Virtual Storage Access Method (VSAM) Options 
for Advanced Applications. 

If you use addressed access to process key-sequenced data, you should 
consider the possibility that RBAs may have changed during previous keyed 
access. 

For examples of keyed and addressed retrieval, storage, deletion, and update, 
see the chapter "Request Macros" later in this publication. 



Retrieve by Key 



Keyed sequential access for a key-sequenced data set depends on where the 
previous macro request positioned VSAM with respect to the key sequence 
defined by the index. When your program opens the data set for keyed access, 
VSAM is positioned at the first record in the data set in key sequence to begin 
keyed sequential processing. The POINT macro instruction positions VSAM 
at the record whose key you specify. If the key is a leading portion of the key 
field, a generic key, the record positioned to is the first of the records having 
the same generic key. A subsequent GET macro retrieves the record VSAM is 
positioned at. The GET then positions VSAM at the next record in key 
sequence. VSAM checks positioning when processing modes are changed 
between requests. The POINT macro can position either forward or backward 
in the data set, depending on whether FWD or BWD was specified for the 
OPTCD operand. 

When you are processing by way of a path, records from the base cluster are 
returned according to ascending or, if you are retrieving the previous record, 
descending alternate key values. If there are several records with a nonunique 
alternate key, the records are returned in the order in which they were 
entered into the alternate index. VSAM sets a return code in the RPL when 
there is at least one more record with the same alternate key. For example, if 
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there are three data records with the alternate key 1234, the return code 
would be set during the retrieval or records one and two and would be reset 
during retrieval of the third record. 

Keyed sequential retrieval for a relative record data set causes the records to 
be returned in ascending or, if you are retrieving the previous record, 
descending numerical order, based on the current positioning for the data set. 
Positioning is established in the same way as for a key-sequenced data set, 
and the relative record number is treated as a full key. If a deleted record is 
encountered during sequential retrieval, it is skipped over and the next record 
is retrieved. The relative record number of the retrieved record is returned in 
the ARG field of the RPL. 

Keyed direct retrieval for a key-sequenced data set does not depend on prior 
positioning; VSAM searches the index from the highest level down to the 
sequence set to retrieve a record. You can specify the record to be retrieved 
by supplying one of the following: 

• The exact key of the record 

• An approximate key, less than or equal to the key field of the record 

• A generic key 

You can use approximate specification when you do not know the exact key. 
If a record actually has the key specified, VSAM retrieves it; otherwise, it 
retrieves the record with the next higher key. Generic key specification for 
direct processing causes VSAM to retrieve the first record having that generic 
key. If you want to retrieve all the records with the generic key, specify NSP 
in your direct request. That causes VSAM to position itself at the next record 
in key sequence. You can then retrieve the remaining records sequentially. 

When you use direct or skip-sequential access to process a path, a record 
from the base data set is returned according to the alternate key you have 
specified in the ARG operand of the RPL macro. If the alternate key is not 
unique, the record which was first entered with that alternate key is returned 
and a return code (duplicate key) is set in the RPL. To retrieve the remaining 
records with the same alternate key, specify the NSP option when retrieving 
the first record and then switch to sequential processing. 

To use direct or skip-sequential access to process a relative record data set, 
you must supply the relative record number of the record you want in the 
ARG operand of the RPL macro. If you request a deleted record, the request 
will cause a no-record-found logical error. 

When you indicate the key of the next record to be retrieved during 
skip-sequential retrieval, VSAM skips to its index entry by using horizontal 
pointers in the sequence set to get to the appropriate sequence-set index 
record to scan its entries. TJie key of the next record must always be higher in 
sequence than the key of the preceding record. 

A relative record data set has no index; VSAM takes the number of the 
record to be retrieved and calculates the control interval that contains it and 
its position within the control interval. 
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Delete by Key 



An ERASE macro instruction that follows a GET for update deletes the 
record that the GET retrieved. A record is physically erased in the data set 
when you delete it. The space the record occupied is then available as free 
space. 

You can erase a record from the base cluster of a path only if the base cluster 
is a key-sequenced data set. If the alternate index is in the upgrade set (that 
is, UPGRADE was specified when the alternate index was defined), it is 
modified automatically when you erase a record. If the alternate key of the 
erased record is unique, the alternate index data record with that alternate key 
is also deleted. 

You can erase a record from a relative record data set after you have 
retrieved the record for update. The record is set to binary zeros and the 
control information for the record is updated to indicate an empty slot. You 
can reuse the slot by inserting another record of the same length into it. 



Store by Key 



To store records in ascending key sequence throughout a data set, you can use 
sequential, skip-sequential, or direct access. For sequential or skip-sequential 
processing, VSAM scans the sequence set of the index; for direct processing, 
VSAM searches the index from top to bottom. 

A PUT macro instruction stores a record. A PUT for update following a GET 
for update stores the record that the GET retrieved. To update a record, you 
must previously have retrieved it for update. 

When VSAM detects that two or more records are to be inserted in sequence 
into a collating position (between two records) in a data set. VSAM uses a 
technique called mass sequential insertion to buffer the records being 
inserted, thereby reducing I/O operations. Using sequential instead of direct 
access in this case enables you to take advantage of this technique. You can 
also extend your data set (resume loading) by using sequential insertion to 
add records beyond the highest key or relative record number. 

Sequential insertion in a relative record data set causes a record to be assigned 
the next available number in sequence, which is the next available relative 
record number greater than the position established by a previous record. The 
assigned number is returned in the ARG field of the RPL. 

Direct or skip-sequential insertion of a record into a relative record data set 
causes the record to be placed as specified by the relative record number in 
the ARG field of the RPL. You must insert the record into a slot that does 
not contain a record. 

You can insert and update data records in the base cluster by way of a path, 
provided the PUT request does not result in nonunique alternate keys in an 
alternate index which you have defined with the UNIQUE parameter. If the 
alternate index is in the upgrade set (that is, you specified UPGRADE when 
you defined the alternate index), the alternate index is modified automatically 
when you insert or update a data record in the base cluster. If the updating of 
the alternate index results in an alternate-index record with no pointers to the 
base cluster, the alternate-index record is erased. 
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Retrieve by Address 



Positioning for addressed sequential retrieval is done by RBA rather than by 
key. When a processing program opens a data set for addressed access, 
VSAM is positioned at the first record in the data set in entry sequence to 
begin addressed sequential processing. A POINT positions VSAM for 
sequential access beginning at the record whose RBA you have indicated. A 
sequential GET causes VSAM to retrieve the data record at which it is 
positioned and positions VSAM at the next record in forward or backward 
direction. 

With direct processing, you can optionally specify that the position be 
maintained following the GET. Your program can then process the 
subsequent records sequentially in either a forward or backward direction. 

Addressed sequential access retrieves records in forward or backward 
direction. If addressed sequential retrieval is used for a key-sequenced data 
set, records will not be in their key sequence if there have been control 
interval or control area splits. 

Addressed direct retrieval requires that the RBA of each individual record be 
specified, since previous positioning is not applicable. The address specified 
for a GET or a POINT must correspond to the beginning of a data record; 
otherwise, the request is invalid. 



Delete by Address 



Store by Address 



The ERASE macro can be used only with a key-sequenced data set to delete 
a record that you have previously retrieved for update. 

With an entry-sequenced data set, you are responsible for marking a record 
you consider to be deleted. As far as VSAM is concerned, the record is not 
deleted. You can reuse the space occupied by a record marked as deleted by 
retrieving the record for update and storing in its place a new record of the 
same length. 



VSAM does not insert new records into an entry-sequenced data set, but adds 
them at the end. With addressed access of a key-sequenced data set, VSAM 
does not insert or add new records. 

A PUT macro instruction stores a record. A PUT for update following a GET 
for update stores the record that the GET retrieved. To update a record, you 
must previously have retrieved it for update. You can update the contents of a 
record with addressed access, but you cannot alter the record's length. 
Neither can you alter the prime key field of a record in a key-sequenced data 
set. 

To change the length of a record in an entry-seqeunced data set, you must 
store it either at the end of the data set (as a new record) or in the place of an 
inactive record of the same length. You are responsible for marking the old 
version of the record as inactive. 
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Exit Routines for Special Processing 



An exit is a branch that VSAM takes to an optional user-supplied routine 
when certain unusual conditions occur or when certain recurrent but 
unpredictable events happen. Exits are defined for: 

• Logical error (LERAD), which is used when the processing program makes 
an invalid request for access to data. 

• Physical error (SYNAD), which is used to handle physical-error conditions. 

• Exception handling (EXCEPTIONEXIT), which monitors physical-error 
conditions on a data set basis. This exit is specified via the Access Method 
Services DEFINE command and it is taken before a SYN AD exit if both 
are specified. 

• End of data set (EODAD), which is used when the processing program has 
attempted to point to or retrieve sequentially a record beyond the last 
record in the data set. 

• Journalizing a transaction or keeping track of RBA change (JRNAD), 
which is used to keep track of of any change to the RBAs of records. 

• User-security- verification (USVR), which is used to make security checks 
in addition to verification of passwords. 

The routine to which VSAM exits may be a subroutine in the processing 
program or a separate load module. An exit routine is identified as available 
for use in an exit list associated with one or more access-method control 
blocks. See the chapter "Control Block Macros" for information on how the 
exit list is created, modified, tested, and displayed. See the chapter 
"User- Written Exit Routines" for detailed information about the exit 
routines. For information about exception exits, see the appropriate Access 
Method Services publication. 



Utility Functions Carried Out by Access Method Services 



Access Method Services is a multifunction service program that is used to 
define a VSAM data set and load records into it, convert a sequential or an 
indexed-sequential data set to the VSAM format, list VSAM catalog 
information or data-set records, copy a data set for reorganization, create a 
backup copy of a data set, recover from certain types of damage to a data set, 
and make a data set portable from one operating system to another. 
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Processing a VSAM Data Set with an ISAM Program 



VSAM provides an interface program that permits you to use programs coded 
to use ISAM (indexed-sequential access method) to process VSAM data sets. 
To use the ISAM interface, you must convert indexed-sequential data sets to 
VSAM data sets, convert ISAM JCL to VSAM JCL, and ensure that your 
existing ISAM programs meet the restrictions for using the interface. 

To convert an indexed-sequential data set to a VSAM data set that you can 
process either with an ISAM program by way of the ISAM interface or with a 
VSAM program, you use Access Method Services to define a key-sequenced 
data set in a VSAM catalog and allocate space for it. You may use an ISAM 
program by way of the ISAM interface to load records into the data set, or 
you may use Access Method Services REPRO command. For more details 
about the procedure, see the chapter "Using ISAM Programming with 
VSAM." 



Using the Time Sharing Option (TSO) with VSAM 



TSO is a subsystem of OS/VS2 that provides conversational time sharing 
from remote terminals. You can use TSO with VSAM to: 

• Execute Access Method Services commands directly as TSO commands. 

• Execute a program to process a VSAM data set. 

• Execute a program to call Access Method Services. 

• Dynamically allocate a VSAM data set and use VSAM macros to process 
the data set. 

• Allocate a VSAM data set by way of a LOGON procedure and use either 
VSAM or ISAM macros to process the data set. 

For details about writing and executing programs and allocating data sets with 
TSO, see OS/VS2 TSO Terminal User's Guide, and OS/VS2 TSO 
Command Language Reference. For information about dynamic allocation, 
see OS/VS2 JCL. 
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OPENING AND CLOSING A DATA SET 



How to Code JCL 



This chapter describes (1) the job control language, required in VS1 and 
optional in VS2, used to connect a data set and the program that is to use it, 
how to code the VSAM AMP parameter, and how to identify user catalogs 
for jobs or job steps; (2) the OPEN macro; and (3) the CLOSE macro. 

A necessary link between a processing program and the data set to be 
processed is the data-set name. When JCL is used, the access-method control 
block gives the name of the DD statement so that the OPEN macro can make 
the connection between the program and the data set named in the DD 
statement, and thus connect program and data. When JCL is not used, the 
data set can be dynamically allocated. See OS/VS2 JCL and OS/VS2 
System Programming Library: TSO for an explanation of dynamic 
allocation. 



All VSAM data sets are cataloged in a VSAM catalog. To identify a VSAM 
data set through JCL, it is sufficient to specify a DD statement of the form: 

//ddname DD DSNAME=^«ame,DISP={OLD | SHR} 

The DSNAME parameter specifies the name of the data set you are 
processing. Each VSAM data set is defined as a component of a cluster: a 
key-sequenced data set is made up of a data component and an index 
component; and an entry-sequenced and a relative record data set are made 
up of only a data component. If you need to process a component separately, 
you may specify the component's name in the DSNAME parameter. 

If a data set in a job step is defined in a user catalog, it is also necessary to 
identify the user catalog either by means of a JOBCAT or a STEPCAT DD 
statement or by means of dynamic allocation. 

Because the operating system does not disallow OS/VS DD parameters and 
subparameters that don't apply to a VSAM data set, you should be aware of 
the DD parameters and subparameters that have clear and unambiguous 
meaning when used with VSAM. Figure 2 shows the DD parameters and 
subparameters that can be used with VSAM and indicates their meaning for a 
VSAM data set. DD parameters and subparameters not shown in Figure 2 
should be avoided. For an explanation of potential problems you may 
encounter with those parameters and subparameters, see the appropriate 
Access Method Services publication. 



Coding a DD Statement for a User Catalog 



The master catalog is assumed to contain the definition of the data set 
described in a DD statement if no user catalog is indicated or if the definition 
is not found in the user catalog(s) that are indicated. A user catalog is 
specified either for all of the steps of a job or for a particular step. To specify 
a job user catalog, place a DD statement with the ddname JOBCAT before 
the first EXEC statement after the JOB statement and after a JOBLEB 
statement, if any: 

//EXAMPLE JOB . . . 

//JOBLIB DD DSNAME=USER . LIB , DISP=SHR 

//JOBCAT DD DSNAME=usercatalogname,DISP=SHR 

// EXEC . . . 
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Parameter Subparameter Comment 
DDNAME ddname Works as in OS/VS. 



DISP SHR 



OLD 

PASS 

DSNAME dsname 
DUMMY 



UNIT 



address 

type 

group 

P 



unitcount 



DEFER 
VOLUME PRIVATE 
RETAIN 
SER 



Indicates that you are willing to share the data set with other 
jobs. This subparameter alone, however, does not guarantee 
that sharing will take place. See the appropriate Access 
Method Services publication for a full description of data-set 
sharing. 

Works as in OS/VS; if specified for a VSAM catalog, 
however, defaults to SHR. 

Works as in OS/VS if data and index components reside on 
the same type of device. 

Works as in OS/VS. 

Works as in OS/VS, except that an attempt to read results in 
an end-of-data condition, and an attempt to write results in a 
return code that indicates the write was successful. If 
specified, AMP='AMORG' must also be specified (see 
"Coding the AMP Parameter" later in this chapter). 

Must be the address of a valid device for VSAM. If not, 
OPEN will fail. 

Must be a type supported by VSAM. If not, OPEN will fail. 

Must be a group supported by VSAM. If not, OPEN will fail. 

There must be enough units to mount all of the volumes 
specified. If sufficient units are available, UNIT»p can 
improve performance by avoiding the mounting and 
demounting of volumes. 

If the number of devices requested is greater than the number 
of volumes on which the data set resides, the extra devices are 
allocated anyway. If data and index components reside on 
unlike devices, the extra devices are allocated evenly between 
the unlike device types. If the number of devices requested is 
less than the number of volumes on which the data set resides 
but greater than the minimum number required to gain access 
to the data set, the devices over the minimum are allocated 
evenly between unlike device types. If devices beyond the 
count specified are in use by another task but are shareable 
and have mounted on them volumes containing parts of the 
data set to be processed, they will also be allocated to this 
data set. 

Works as in OS/VS. 

Works as in OS/VS. 

Works as in OS/VS. 

The volume serial number(s) used in the Access Method 
Services DEFINE command for the data set must match the 
volume serial numbers in the VOLUME— SER specification 
when the data set is defined. After a VSAM data set is 
defined, the volume serial number(s) need not be specified on 
a DD statement to retrieve or process the data set. If, 
however, VOLUME-SER and UNIT-type are specified, 
only those volumes specifically named are initially mounted. 
Other volumes may be mounted when they're needed if at 
least one of the units allocated to the data set is not shareable 
and the number of OPENs issued against the volume is less 
than or equal to 1, or the unit count is greater than the total 
number of volumes initially mounted. One unit is made 
unshareable when unit count is less than the number of 
volume serial numbers specified or when DEFER is specified. 



Figure 2. JCL DD Parameters 
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To specify a job-step user catalog, place a DD statement with the ddname 
STEPCAT after the EXEC statement of the step: 

// EXEC . . . 

//STEPCAT DD DSNAME=usercatalogname,DISP=SHR 

The order in which catalogs are searched when an existing entry is to be 
located is: 

• If a catalog is specified in a CATALOG parameter, only that catalog is 
searched. In VS1, if a catalog is specified in the CATALOG parameter and 
it is not also a master, STEPCAT, or JOBCAT catalog, the dname 
parameter must also be specified in CATALOG. 

• Any user catalog(s) specified in the current job step (STEPCAT) or, if 
none is specified for the job step, any user catalog(s) specified for the 
current job (JOBCAT). If more than one catalog is specified for the job 
step or job, the job-step or job catalogs are searched in order of 
concatentation. 

• For VS1 , if the entry is not found, the master catalog. 

• For VS1, if the entry is not found, the system catalog. 

• For VS2, if the entry is not found and the entry's name is a qualified name 
and the first qualifier (that is, the first one to eight characters before any 
period) is the same as the name or alias of a user catalog or the alias of a 
control volume, that user catalog or control volume is searched; otherwise, 
the master catalog. 

Restriction: Control volumes are not searched when (1) an existing data set is 
to be deleted except when the data set to be deleted is a nonVSAM data set, 
or (2) when an existing data set is to be altered. 

Coding the AMP Parameter 

VSAM uses one additional JCL parameter: AMP. It has subparameters for: 

• Overriding operands specified by way of the ACB, EXLST, and GENCB 
macros 

• Supplying operands missing from the ACB or GENCB macro 

• Indicating checkpoint/restart options 

• Indicating options when using ISAM macros to process a key-sequenced 
data set 

• Indicating that the data set is a VSAM data set when you specify unit and 
volume information or DUMMY in the DD statement 

• Indicating that you want VSAM to supply storage dumps of the 
access-method control block(s) that identify this DD statement 

The AMP parameter takes effect when the data set defined by the DD 
statement is opened. 
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The format of the AMP parameter is: 



//... 


DD 


...[AMP= ['AMORG'] 
[,'BUFND= number'] 
[,'BUFN1= number'] 
[,'BUFSP= number'] 
[,'CROPS={RCK | NCK | NRE | NRC}'] 
[,'OPTCD={I|L|IL} , ] 
[,<RECFM={F | FB | V | VB}'] 
[,«STRNO= number'] 
[, t SYNAD=modulename '] 
[/TRACE']] 



where: 

AMORG 

specifies that the DD statement defines a VSAM data set. You need to 
(and must) specify AMORG only when you include unit and volume 
information or DUMMY in the DD statement. When you specify unit and 
volume information or DUMMY, the system doesn't have to search a 
catalog to find out what volume(s) are required, and therefore doesn't 
know that the DD statement defines a VSAM data set. You never have to 
specify unit and volume information unless you want to have a subset of 
the volumes on which the data set is stored mounted or want to cause 
mounting to be deferred. 

BUFND=number 

BUFNI=number 

BUFSP=number 

specifies that one or more of these values is to override whatever was 
specified in the ACB or GENCB macro, or that one or more of these 
values is to be provided if not previously specified. 

CROPS= {RCK | NCK | NRE | NRC} 

specifies one of four checkpoint/restart options, which are described in 
detail in OS/VS Checkpoint /Restart. If you specify an option that is not 
applicable for a data set, such as the data-erase test for an input data set, 
the option is ignored. 

RCK 

specifies that a data-erase test and data-set-post-checkpoint 
modification tests are to be performed. 

NCK 

specifies that data-set-post-checkpoint modification tests are not to be 
performed. 



NRE 



specifies that a data-erase test is not to be performed. 

NRC 

specifies that neither a data-erase test nor data-set-post-checkpoint 
modification tests are to be performed. 

OPTCD={I|L|IL} 

specifies the processing of records flagged for deletion (binary Is in the 
first byte) with an ISAM processing program using the ISAM interface. I 
and L are described in the chapter "Using ISAM Programming with 
VSAM." 
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RECFM={F|FB|V|VB} 

specifies record format in the same way as the DCB (data control block) 
parameter that is used for processing an indexed-sequential data set. You 
use it when processing a VSAM data set with an ISAM processing program 
to indicate what record format the processing program assumes. The 
options are described in the chapter "Using ISAM Programming with 
VSAM." 

STRNO=number 

specifies a value that is to override the STRNO value specified in the ACB 
or GENCB macro, or to provide a value if one was not specified. 

SYN AD =modulename 

specifies a value that is to override the address of a SYNAD exit routine 
specified in the EXLST or GENCB macro that generates the exit list. The 
exit list intended is the one whose address is specified in the access-method 
control block that links this DD statement to the processing program. If no 
SYNAD exit was specified, the SYNAD parameter of AMP is ineffective. 
You can also use this parameter, when you are processing a VSAM data 
set with an ISAM processing program, to provide an ISAM SYNAD 
routine or to replace one with another. 

TRACE 

specifies that Generalized Trace Facility (GTF) is to be active, along with 
your processing job, to gather information associated with opening and 
closing data sets and end-of -volume processing. You can print the trace 
output with the IMDPRDMP service program. 

Note: See "AMP Parameter Specification" in the chapter "Using ISAM 
Programming with VSAM" for additional information on the use of the AMP 
parameter with an ISAM processing program. 

Subparameters must be enclosed in apostrophes. Apostrophes can enclose 
each individual subparameter or group of subparameters. If you have more 
than one pair of apostrophes, you must enclose all of the subparameters in a 
pair of parentheses. For example, AMP ='AMORG /TRACE' or 
AMP=('AMORG7TRACE'). If the subparameters continue from one line to 
another, a pair of apostrophes cannot extend from one line to the next, and 
you must therefore use a pair of parentheses to enclose all of the 
subparameters. 

The AMP parameter cannot be defined as a symbolic parameter (a symbol 
preceded by an ampersand that stands for a parameter or the value assigned 
to a parameter or subparameter in a cataloged or in-stream procedure). 



OPEN Macro (Connect Program and Data) 



Before your program can issue requests for access to a data set, it must open 
the data set for processing. Opening a data set causes VSAM to have the 
volume(s) on which it is stored mounted if necessary and to verify that the 
data set matches the description implied by the ACB or GENCB macro (for 
example, MACRF=KEY implies that the data set is a key-sequenced data 
set). 

OPEN causes VSAM to construct control blocks (other than those you 
caused to be built by the ACB, EXLST, and GENCB macros) that it needs to 
process your requests for access to the data set. It determines what processing 
options are to be used by merging the information in the DD statement and 
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the catalog definition of the data set with the information in the 
access-method control block and the exit list. The order of precedence is: 

1. The DD-statement AMP parameters 

2. The ACB, EXLST, or GENCB operands 

3. The catalog entry for the data set 

For example, if information about buffer space is specified both in the DD 
statement and in the ACB or GENCB macro, the values in the DD statement 
override those in the macro. Catalog information acts as a default when 
buffer space specified in the DD statement or in the macro is less than the 
minimum specified when the data set was defined or when buffer space is 
specified in neither the DD statement nor the macro. 

VSAM also checks the password that your program specified against the 
appropriate password (if any) in the catalog definition of the data set. The 
password required depends on the kind of access specified in the 
access-method control block (for example, is access for retrieval or for 
update), as follows: 

• Full access allows you to perform all operations (retrieving, updating, 
inserting, and deleting) on a data set and any index or catalog record 
associated with it. The master password allows you to delete or alter the 
catalog entry for the data set or catalog it protects. 

• Control-interval access requires the control password. The control 
password allows you to use control-interval access and to retrieve, update, 
insert, or delete records in the data set it protects. See OS/VS Virtual 
Storage Access Method (VSAM) Options for Advanced Applications, for 
information on the use of control-interval access. 

• Update access requires the update password. The update password allows 
you to retrieve, update, insert, or delete records in the data set it protects. 

• Read access requires the read password. The read password allows you to 
examine records in the data set it protects; the read password does not 
allow you to add, change, or delete records. 

A password of one level authorizes you to do everything that a password of a 
lower level authorizes you to do. Password protection is further described in 
the appropriate Access Method Services publication. 

The format of the OPEN macro is: 



[label] 


OPEN 


{address [^options )],.••) 



where: 

label 

is one to eight characters that provides a symbolic address for the OPEN 
macro. 

address 

specifies the address of the access-method control block or DCB for the 
data set(s) to be opened. You may specify the address in register notation 
(using a register from 2 through 12 — in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. If 
you use register notation to open only one data set, you must enclose the 
expression identifying the register in two sets of parentheses: for example, 
OPEN ((2)). 
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options 

are options parameters for use only in opening nonVSAM data sets. If any 
options are specified with the address of an access-method control block, 
VSAM ignores them. 

Because the OPEN operands are positional, include a comma for options 
(even if you don't specify options) before a subsequent operand. 



Return Codes from OPEN 



When your program receives control after it has issued an OPEN macro, 
register 15 indicates whether all of the VSAM data sets were opened 
successfully: 

Reg. 15 Condition 

All data sets were opened successfully. 

4 All data sets were opened successfully, but one or more warning messages were 

issued (codes less than X'80'). 

8 At least one data set (VSAM or nonVSAM) was not opened successfully; the 

access-method control block was restored to the contents it had before OPEN 
was issued, or, if the data set was already open, the access-method control block 
remains open and is not changed. 

12 A nonVSAM data set was not opened successfully when a nonVSAM and a 

VSAM data set were being opened at the same time; the nonVSAM data control 
block was not restored to the contents it had before OPEN was issued (and the 
data set cannot be opened without the control block's being restored). 

If register 15 contains 4, 8, or 12, you can find out whether a VSAM data set 
had a warning message, or wasn't opened successfully and why, by issuing 
SHOWCB to display the ERROR field in each access-method control block 
specified in OPEN. (See "SHOWCB Macro (Display an Access-Method 
Control Block)" in the chapter "Control Block Macros.") Figure 3 shows the 
possible return codes that you may get from OPEN in the ERROR field in the 
access-method control block. In addition to these return codes, VSAM writes 
a message to the operator console and the programmer's listing to further 
explain the error. See OS/VS Message Library: VS1 System Messages and 
OS/VS Message Library: VS2 System Messages for a listing of VSAM 
messages for VS1 and VS2, respectively. 



Example: OPEN Macro 



In this example, an OPEN macro is used to open two data sets. The 
access-method control block for one data set was generated at execution; the 
other was generated at assembly. 



GENCB 



BLK=ACB, 
DDNAME=DATA 



LR 2,1 

OPEN (BLOCK,,(2)) 



BLOCK 



ACB 



An access-method control block. 

Address of the control block. 

A label is used for the access-method 
control block generated by ACB; 
register notation is used for the one 
generated by GENCB. The two 
commas indicate the omission of 
options. 

Another access-method control block. 



Opening and Closing a Data Set 35 



Code Condition 

When register 15 contains 0, no error. When register 15 contains 8, either (1) 

VSAM is processing the access-method control block for some other request, (2) 
the access-method control block is already open, (3) the DDNAME was not 
specified correctly in the access-method control block, or (4) the access-method 
control block address is invalid. 

4 The data set indicated by the access-method control block is already open. 

96 Warning message: an unusable data set was opened for input. 

100 Warning message: OPEN encountered an empty alternate index that is part of an 
upgrade set. 

104 Warning message: the time stamp of the volume on which a. data set is stored 

doesn't match the system time stamp in the data set's catalog record; this indicates 
that extent information in the catalog record may not agree with the extents 
indicated in the volume's VTOC. 

108 Warning message: the time stamps of a data component and an index component 
do not match; this indicates that either the data or the index has been updated 
separately from the other. 

1 16 Warning message: the data set was not properly closed. A previous VSAM 
program may have abnormally terminated. Data may be lost if processing 
continues; the Access Method Services VERIFY command may be used to cause 
the data set to be properly closed. See the appropriate Access Method Services 
publication for a description of the VERIFY command. 

132 An uncorrectable I/O error occurred while VSAM was reading the job file control 
block (JFCB). 

136 Not enough virtual-storage space is available in your program's address space for 
work areas, control blocks, or buffers. 

144 An uncorrectable I/O error occurred while VSAM was reading or writing a catalog 
record. 

148 No record for the data set to be opened was found in the available catalog(s), or an 
unidentified error occurred while VSAM was searching the catalog. 

1 52 Security verification failed; the password specified in the access-method control 
block for a specified level of access doesn't match the password in the catalog for 
that level of access. 

160 The operands specified in the ACB or GENCB macro are inconsistent with each 
other or with the information in the catalog record. 

164 An uncorrectable I/O error occurred while VSAM was reading the volume label. 

168 The data set is not available for the type of processing you specify, or an attempt 
was made to open a reusable data set with the reset option while another user had 
the data set open. 

176 An error occurred while VSAM was attempting to fix a page of virtual storage in 
real storage. 

180 A VSAM catalog specified in JCL either does not exist or is not open, and no 
record for the data set to be opened was found in any other catalog. 

184 An uncorrectable I/O error occurred while VSAM was completing an I/O request. 

1 88 The data set indicated by the access-method control block is not of the type that 
may be specified by an access-method control block. 

192 An unusable data set was opened for output. 

196 Access to data was requested via an empty path. 

Figure 3 (Part 1 of 2). OPEN Return Codes in the ERROR Field of the Access-Method 
Control Block 
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Code Condition 

200 Volume is unusable 

204 The ACB MACRF specification is GSR and caller is not operating in protect 
key 7 1 . 

208 The ACB MACRF specification is GSR and caller is using a VS1 system 1 . 

212 The ACB MACRF specification is GSR or LSR and the data set requires create 
processing 1 . 

216 The ACB MACRF specification is GSR or LSR and the key length of the data set 
exceeds the maximum key length specified in BLDVRP 1 . 

220 The ACB MACRF specification is GSR or LSR and the data set's control interval 
size exceeds the size of the largest buffer specified in BLDVRP 1 . 

224 Improved control interval processing is specified and the data set requires create 
mode processing 1 . 

232 Reset was specified for a nonreusable data set and the data set is not empty. 

236 Indicates a stage or destage error. 

240 Format-4 DSCB and catalog timestamp verification failed during volume mount 
processing for output processing. 

244 The volume containing the catalog recovery area was not mounted and verified for 
output processing. 

1 Options and restrictions are described in OS/VS Virtual Storage Access Method 
(VSAM)Options for Advanced Applications. 



Figure 3 (Part 2 of 2). 



OPEN Return Codes in the ERROR Field of the Access-Method 
Control Block 



CLOSE Macro (Disconnect Program and Data) 



Disconnecting your program from a data set causes VSAM to write out any 
buffers of data or index whose contents have changed and which haven't 
already been written out. It causes VSAM to put back into the catalog the 
updated information that was brought into virtual storage when the data set 
was opened, and to write records in the SMF data set if you are using SMF. 
VSAM also releases virtual-storage space and restores your access-method 
control block(s) to the contents they had when the OPEN macro was issued. 
To process the data set again, you must reopen it. 

The format of the CLOSE macro is: 



{label] 


CLOSE 


{address [Options )],.••) 
[,TYPE=T] 



where: 

label 

is one to eight characters that provides a symbolic address for the CLOSE 
macro. 

address 

specifies the address of the access-method control block or DCB for each 
data set to be closed. You may specify the address in register notation 
(using a register from 2 through 12 — in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. If 
you specify only one address with a register, you must enclose the 
expression identifying the register in two sets of parentheses: for example, 
CLOSE ((2)). 
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options 

are options parameters for use only in closing nonVSAM data sets. If any 
options are specified with the address of an access-method control block, 
VSAM ignores them. Because the CLOSE operands are positional, include 
a comma for options (even if you don't specify options) before a 
subsequent operand. 

TYPE=T 

specifies that VSAM is to complete outstanding I/O operations and update 
the catalog, but not disconnect the program from the data. 

You can issue a temporary CLOSE macro to cause VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. A 
temporary CLOSE doesn't disconnect the program from the data set, so your 
program can continue to process the data set without issuing an OPEN macro 
again. 

You must close and reopen a newly loaded VSAM data set before you can 
issue GETs and PUTs. A temporary close is not adequate for this purpose. 

Note: If you are subtask-sharing or if you have issued an asynchronous 
request for access to a data set, you must issue a CHECK or an ENDREQ on 
all RPLs before you issue a temporary CLOSE. Concurrent data set I/O 
activity will cause unpredictable results during a temporary close. 



Return Codes from CLSO E 



When your program receives control after it has issued a CLOSE macro, 
register 15 indicates whether all of the VSAM data sets were closed 
successfully: 

Reg. 15 Condition 

All data sets were closed successfully. 

4 At least one data set (VSAM or nonVSAM) was not closed successfully. 

If register 15 contains 4, you can use SHOWCB to display the ERROR field 
in each access-method control block to find out whether a VSAM data set 
wasn't closed successfully and why. (See "SHOWCB Macro (Display an 
Access-Method Control Block)" in the chapter "Control Block Macros.") 
Figure 4 gives the return codes that the ERROR field may contain following 
CLOSE. In addition to these return codes, VSAM writes a message to the 
operator's console and the programmer's listing to further explain the error. 
See OS/VS Message Library: VS1 System Messages and OS/VS Message 
Library: VS2 System Messages, for a listing of messages for VS1 and VS2, 
respectively. 



38 OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide 



Code Condition 

No error (set when register 15 contains 0). 

4 The data set indicated by the access-method control block is already closed. 

132 An uncorrectable I/O error occurred while VSAM was reading the job file control 
block (JFCB). 

136 Not enough virtual storage was available in your program's address space for a 
work area for CLOSE. 

144 An uncorrectable I/O error occurred while VSAM was reading or writing a catalog 
record. 

148 An unidentified error occurred while VSAM was searching the catalog. 

184 An uncorrectable I/O error occurred while VSAM was completing outstanding 
I/O requests. 

Figure 4. CLOSE Return Codes 
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CONTROL BLOCK MACROS 



The control block macros are used to build control blocks and to modify, 
display, and test their contents. Some of these macros work at assembly time; 
others work at execution time. The macros are: 

• ACB, which is used to generate an access-method control block at 
assembly time. An access-method control block must exist before a data 
set can be opened. 

• EXLST, which is used to generate an exit list at assembly time. An exit list 
is a list of user-written routines that can be associated with one or more 
access-method control blocks. Except for an exception exit, which is 
specified via Access Method Services, a user-written routine must be 
identified in an exit list to be available to handle unusual conditions. 

• RPL, which is used to generate a request parameter list at assembly time. A 
request parameter list is required for use with the request macros to define 
the characteristics of the request. 

• GENCB, which is used to generate an access-method control block, an exit 
list, or a request parameter list at execution time. An access-method 
control block must exist before a data set can be opened. An exit list 
identifies any user-written routines provided. A request parameter list is 
required to define (specify processing) an action for a request macro. 

• MODCB, which is used to modify or make an addition to an 
access-method control block, an exit list, or a request parameter list at 
execution time. 

• SHOWCB, which is used to display fields in an access-method control 
block, an exit list, or a request parameter list at execution time. 

• TESTCB, which is used to test the contents of fields in an access-method 
control block, an exit list, or a request parameter list at execution time. 

Generating a control block at assembly time (ACB, EXLST, and RPL 
macros) has the advantage of generating the control block only once. When a 
control block is generated at assembly time, you are, however, exposed to the 
possibility of having to reassemble your program if you adopt a new version 
of VSAM in which the format of a control block has changed. Generating a 
control block at execution time (GENCB macro) has the advantage of not 
requiring reassembly of a program if the format of a control block changes in 
a subsequent version of VSAM. It has the disadvantage of having to execute 
the macro each time the program is executed. 



Specifying Options at Assembly or Execution 



For specifying processing options, you can use macros that generate control 
blocks when your program is assembled (ACB, EXLST, and RPL macros) or 
use a macro that generates control blocks when the program is executed 
(GENCB macro). 

The macros that work at assembly time allow you to specify values for 
operands as absolute numeric expressions, as character strings, as codes, as 
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expressions that generate valid relocatable A-type address constants. The 
macros that work at execution allow you to specify them in those ways and 
also in: 

• Register notation, where the expression designating a register from 2 
through 12 is enclosed in parentheses; for example, (2) and (REG), where 
REG is a label equated to a number from 2 through 12 

• An expression of the form (S,scon), where scon is an expression valid for 
an S-type address constant, including the base-displacement form 

• An expression of the form (*,scon), where scon is an expression valid for 
an S-type address constant, including the base-displacement form, and the 
address specified by scon is indirect — that is, it gives the location of the 
area that contains the value for the operand 

For most programming applications, you can conveniently use register 
notation or absolute numeric expressions for numbers, character strings for 
names, and register notation or expressions that generate valid A-type address 
constants for addresses. "Appendix C: Operand Notation for GENCB, 
MODCB, SHOWCB, and TESTCB" gives all the ways of coding each 
operand for the macros that work at execution time. 

You can write a reentrant program only with execution-time macros. 
"Appendix B: List, Execute, and Generate Forms of GENCB, MODCB, 
SHOWCB, and TESTCB" describes alternate ways of coding these macros 
for reentrant programs. The standard form of these macros is described in this 
chapter. 



Return Codes from the GENCB, MODCB, SHOWCB, and 
TESTCB Macros 



The GENCB, MODCB, SHOWCB, and TESTCB macros are executable 
(unlike the ACB, EXLST, and RPL macros): they cause control to be given 
to VSAM to perform the indicated task. VSAM indicates the task was 
completed by a code in register 15: 

Reg. 15 Condition 

Task completed. 

4 Task not completed. 

8 An attempt was made to use the execute form of a macro (see "Appendix B: 

List, Execute, and Generate Forms of GENCB, MODCB, SHOWCB, and 
TESTCB") to modify a keyword that isn't in the parameter list. 

When register 15 contains 4, register contains a code indicating the reason 
VSAM couldn't perform the task. Figure 5 describes each error code that can 
be returned in register 0. 

These macros build a parameter list that describes in codes the actions 
indicated by the operands you specify. The parameter list is passed to VSAM 
to take the indicated actions. An error can occur because you specified the 
operands incorrectly or, if you constructed the parameter list yourself, 
because the parameter list was encoded incorrectly. If you construct the list 
yourself you can also get in register reason codes 1, 2, 3, 10, 14, and 18. 
See OS/VS Virtual Storage Access Method (VSAM) Options for 
Advanced Applications for an explanation of these reason codes and for an 
explanation of how to construct parameter lists for GENCB, MODCB, 
SHOWCB, and TESTCB. 
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Return 
Code 


Applicable 
Macros* 


1 


G,M,S,T 


2 


G,M,S,T 


3 


G,M,S,T 


4 


M,S,T 



Reason VSAM Couldn't Perform the Task 

The request type (generate, modify, show, or test) is invalid. 

The block type (access-method control block, exit list, or request parameter list) is invalid. 

One of the keyword codes in the parameter list is invalid. 

The block at the address indicated is not of the type you indicated (access-method control block, 
exit list, or request parameter list). 

5 S,T Access-method control block fields were to be shown or tested, but information is available only 

when the data set is an open VSAM data set, and either it isn't open or it is not a VSAM data set. 

6 S,T Access-method control block information about an index was to be shown or tested, but no index 

was opened with the data set. 

7 M,S An exit list was to be modified or shown, but the exit indicated isn't present in the exit list. (With 

TESTCB, if the indicated exit isn't present, you get an unequal condition.) 

8 G There isn't enough virtual storage in your program's address space to generate the access-method 

control block(s), exit list(s), or request parameter list(s) and no work area outside your address 
space was specified; or inconsistent use of AM=VTAM on list and execute forms (either 
AM=VTAM was specified on the list form and not on the execute form, or AM*=VTAM was 
specified on the execute form and not on the list form). 

9 G The work area specified was too small for generation or display of the indicated control block or 

fields. 

10 G,M With GENCB, exit-list control-block type was specified and you specified an exit without giving 

an address. With MODCB, exit-list control-block type was specified and you specified an exit 
without giving an address; in this case, either active or inactive must be specified, but load cannot 
be specified. 

11 M Either (1) a request parameter list was to be modified, but the request parameter list defines an 

asynchronous request that is active (that is, no CHECK or ENDREQ has been issued on the 
request) and thus cannot be modified, or (2) MODCB is already issued for the control block, but 
hasn't yet completed. 

12 M An access-method control block was to be modified, but the data set identified by the 

access-method control block is open and thus cannot be modified. 

13 M An exit list was to be modified, and you attempted to activate an exit without providing a new 

exit address. Because the exit list indicated does not contain an address for that exit, your request 
cannot be honored. 

14 G,M,T One of the option codes (for MACRF, ATRB, or OPTCD) has an invalid combination of option 

codes specified (for example, OPTCD=(ADR,SKP)). 

The work area specified did not begin on a fullword boundary. 

A VTAM keyword or subparameter was specified but the AM=VTAM parameter was not 
specified. AM=VTAM must be specified in order to process a VTAM version of the control 
block. 

Two or more keywords of a mutually exclusive group were specified (for example, ARG and 
NIB). 

A keyword was specified which refers to a field beyond the length of the control block located at 
the address indicated (for example, a VTAM keyword, but the control block pointed to is a 
shorter, nonVTAM block. 

20 S Keywords were specified which apply only if MACRF—LSR or GSR. 

•G-GENCB, M-MODCB, S-SHOWCB, T-TESTCB 

Figure 5. GENCB, MODCB, SHOWCB, and TESTCB Return Codes 
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ACB Macro (Generate an Access-Method Control Block) 



Before you can open a data set for processing, you must create an 
access-method control block that identifies the data set to be opened, 
specifies the type of processing (for example, sequential processing) to be 
done, specifies basic options (for example, buffer size), and indicates whether 
exit routines are to be used while the data set is being processed. 

The ACB macro can be used to build an access-method control block when 
the program is assembled. If you adopt a subsequent release of VSAM in 
which the format of a control block has changed and have generated 
access-method control blocks using the ACB macro, you will have to 
reassemble your program. 

Values for ACB-macro operands can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

VSAM allows multiple access-method control blocks to gain access to the 
same data set and conserves resources by connecting those ACBs to the same 
control block structure. The ACBs must be in the same region, and they must 
be opening to the same base cluster. The connection occurs independently of 
the path selected to the base cluster. 

Through MACRF options, you specify whether sharing is to be based on 
DDNAME (MACRF=DDN) or data set name (MACRF=DSN). If the DDN 
option is selected (or taken as the default), two ACBs that specify the same 
DDNAME Will share the same control block structure. If the DSN option is 
selected, the new ACB will be connected to an existing control block 
structure if: 

• The existing control block structure also specifies DSN and 

• The new and existing control block structures have compatible processing 
options 

To be compatible, both the new ACB and the existing control block structure 
must be consistent in their specification of the following processing options: 

Structure is an entry-sequenced data set 

Structure is a key-sequenced data set 

Structure has MACRF=DFR 

Structure has MACRF =UBF 

Structure has MACRF=ICI 

Structure has MACRF=LSR 

Structure has MACRF=GSR 

Those options that apply to the existing structure must also be specified in the 
new ACB. Conversely, the options that apply to the new ACB must also be 
specified in the existing structure. For example, if the new ACB and the 
existing structure both specify MACRF =DFR, the connection will be made. 
If the new ACB specifies MACRF =DFR and the existing structure specifies 
MACRF=DFR,UBF, no connection will be made. 

If compatibility cannot be established, OPEN tries (within the limitations of 
the share options specified when the data set was defined) to build a new 
control block structure. If it can't, the OPEN fails. 
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The format of the ACB macro is: 



[label] 


ACB 


[AM=VSAM] 

[,BSTRNO= number] 

[,BUFND= number] 

[,BUFNI= number] 

[,BUFSP= number] 

[,CATALOG=YES | NO] 

[,CRA=SCRA | UCRA] 

[,DDNAME=ddname ] 

[,EXLST= address] 

[,MACRF=([ADR][,CNV][,KEY] 
[,CFX | NFX] 
[,DDN | DSN] 
[,DFR | NDF] 
[,DIR][,SEOJ[,SKP] 
[,ICI | NCI] 
[,IN][,OUT] 
[,NIS | SIS] 
[,NRM | AK] 
[,NRS | RST] 
[,NSR|LSR|GSR] 
[,NUB | UBF])] 

[,MAREA= address ] 

[,MLEN= number ] 

[,PASSWD= address] 

[,STRNO= number] 



where: 

label 

is one to eight characters that provides a symbolic address for the 
access-method control block that is assembled and also, if you omit the 
DDNAME operand, serves as the ddname. 

AM=VSAM 

specifies that the access method using this control block is VSAM. 

BSTKNO=number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the object 
being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as 
needed for the access to the base cluster. BSTRNO can influence 
performance. The VSAM control blocks for the set of strings specified by 
BSTRNO are allocated on contiguous virtual storage, whereas this is not 
guaranteed for the strings allocated by dynamic extension. 

BUFND =number 

specifies the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 1 
plus the number specified for STRNO (if you omit STRNO, BUFND must 
be at least 2, because the default for STRNO is 1). The number can be 
supplied by way of the JCL DD AMP parameter as well as by way of the 
macro. The default is the minimum number required. 
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BUFNI=number 

specifies the number of I/O buffers VSAM is to use for transmitting the 
contents of index entries between virtual and auxiliary storage for keyed 
access. A buffer is the size of a control interval in the index. The minimum 
number is the number specified for STRNO (if you omit STRNO, BUFNI 
must be at least 1, because the default for STRNO is 1). You can supply 
the number by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. 

BUFSP=number 

specifies the maximum number of bytes of virtual storage to be used for 
the data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• the amount specified in the catalog (BUFFERSPACE), 

• the amount determined from BUFND and BUFNI, or 

• the minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount is less than the minimum amount of 
storage required to process the data set, VSAM cannot open the data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not less than the minimum number. Then, if required, the 
number of index buffers is decreased until the amount: called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not less than 1 more than the minimum number. Then, if 
required, the number of data buffers is decreased to not less than the 
minimum number. If still required, 1 more is subtracted from the 
number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to less than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. 
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The following examples show how VSAM uses your specifications to 
obtain storage: 

Example 1 : BUFSP not specified 

BUFFERSPACE is 32768 

BUFND is 24576 (Data control interval is 2048) 

BUFNI is 10240 (Index control interval is 1024) 

STRNOisll 

BUFSP will be set to 35840 (the minimum needed to process the data set), 
since this is the largest value. 

Example 2: BUFSP not specified 

BUFFERSPACE is 24576 
BUFND is 10240 (Data control interval is 1024) 
BUFNI is 5 1 20 (Index control interval is 5 1 2) 
STRNO is 1 

BUFSP will be set to 24576, the BUFFERSPACE amount, since this is the 
largest value. 

Example 3: BUFSP not specified 

BUFFERSPACE is 32768 
BUFND is 24576 (Data control interval is 2048) 
BUFNI is 10240 (Index control interval is 1024) 
STRNO is 5 

BUFSP will be set to 34816, the sum of BUFND and BUFNI, since this is 
the largest value. 

Example 4: BUFSP is 30696 

BUFFERSPACE is 30696 

BUFND is 24576 (Data control interval is 2048) 

BUFNI is 10240 (Index control interval is 1024) 

STRNO is 6 

MACRF= (KEY,DIR,OUT) 

BUFND will be reduced to 18432, and BUFNI remains the same, since the 
original BUFND and BUFNI are more than BUFSP. 

Example 5: Same as example 4, except MACRF=(KEY,SEQ,OUT) 

BUFNI will be reduced to 7168 (for 1 more than the STRNO number of 
buffers), and BUFND will be reduced by 2048 to 22528, since the original 
BUFND and BUFNI are more than BUFSP. 

CATALOG=YES | NO 

specifies whether a catalog is being opened as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros. When YES is coded, a catalog must be 
processed with an SVC designed for that purpose. 

CRA=SCRA | UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 
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DVNAME=ddname 

is one to eight characters that identifies the data set that you want to 
process by specifying the JCL DD statement for the data set. You may 
omit DDNAME and provide it by way of the label or by way of the 
MODCB macro before opening the data set. MODCB is described later in 
this chapter. 

EXLST=address 

specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1 or the label of an area you supplied to GENCB for 
the exit list. Omitting this operand indicates that you have no exit routines. 
Exit routines are described in the chapter "User- Written Exit Routines." 

MACRF=([ADR][,CNV][,KEY] 

[,CFX | NFX ] 

[, DDN | DSN] 

[,DFR | NDF ] 

[,DIR][,SEQ][,SKP] 

[,ICI | NCI] 

[,D^][,OUT] 

[, NIS | SIS] 

[, NRM | AIX] 

[,NRS | RST] 

[,NSR | LSR | GSR] 

[,NUB | UBF]) 
specifies the kind(s) of processing you will do with the data set. The 
options must be meaningful for the data set. For example, if you specify 
keyed access for an entry-sequenced data set, you cannot open the data 
set. You must specify all of the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
Figure 6 gives the options; they are arranged in groups, and each group has 
a default value (indicated by underlining). You may specify options in any 
order. You may specify both ADR and KEY to process a key-sequenced 
data set. You may specify both DIR and SEQ; with keyed access, you may 
specify SKP as well. If you specify OUT and want simply to retrieve some 
records as well as update, delete, or insert others, you need not also specify 
IN. 

MAREA=address 

specifies the address of an optional OPEN/CLOSE/TCLOSE message 
area. 

MLEN =number 

specifies the length of an optional OPEN/CLOSE/TCLOSE message 
area. Default=0; maximum=32K. 

PASSWD=address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF operand. The 
first byte of the field pointed to contains the length (in binary) of the 
password (maximum of 8 bytes). Zero indicates that no password is 
supplied. If the data set is password-protected and you don't supply a 
required password in the access-method control block, VSAM gives the 
console operator the opportunity to supply it when you open the data set. 
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Option Meaning 

ADR Addressed access to a key-sequenced or an entry-sequenced data set; RBAs are 
used as search arguments and sequential access is by entry sequence 

CNV Control-interval access 1 

KEY Keyed access to a key-sequenced or relative record data set; keys and relative 
record numbers are used as search arguments and sequential access is by key or 
relative record number 

CFX Control blocks built by OPEN are page-fixed 1 

NFX Control blocks built by OPEN are page-fixed only during actual I/O 

DDN Subtask shared control block connection based on common ddnames 
DSN Subtask shared control block connection based on common data set names 

DFR Writes deferred when possible 1 
NDF Writes not deferred 

DIR Direct access to a key-sequenced, entry-sequenced, or a relative record data set 
SEQ Sequential access to a key-sequenced, entry-sequenced, or a relative record data set 
SKP Skip-sequential access to a key-sequenced or a relative record data set; used only 
with keyed access in a forward direction. 

ICI Processing limited to control-interval processing 1 
NCI Processing other than control-interval processing 

IN Retrieval of records of a key-sequenced, entry-sequenced, or a relative record data 

set 
OUT Storage of new records in a key-sequenced, entry-sequenced, or relative record 

data set (not allowed with addressed access to a key-sequenced data set); update of 

records in a key-sequenced, entry-sequenced, or relative record data set; deletion 

of records from a key-sequenced data set 

NIS Normal insert strategy 

SIS Sequential insert strategy (split control intervals and control areas at the insert 
point rather than at the midpoint when doing direct PUTs) 

NRM The object to be processed is the one named in the specified ddname 

AIX The object to be processed is the alternate index of the path specified by ddname 

NRS Data set is not reusable 

RST Data set is reusable (high-used RBA is reset to during OPEN processing) 

NSR Nonshared resources 
LSR Local shared resources 1 
GSR Global shared resources 1 

NUB Management of I/O buffers is left up to VSAM 
UBF Management of I/O buffers is left up to the user; allowed only with 
control-interval access 1 

1 Described in OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications * 

Figure 6. MACRF Options 

STKNO=number 

specifies the number of requests requiring concurrent data-set positioning 
VSAM is to be prepared to handle. The default is 1. A request is defined 
by a given request parameter list or chain of request parameter lists. See 
"RPL Macro (Generate a Request Parameter List)" and "GENCB Macro 
(Generate a Request Parameter List)" later in this chapter for information 
on request parameter lists. When records are loaded into an empty data set, 
the STRNO value in the access-method control block must be 1 . 

OS/VS dynamically extends the number of strings as needed by concurrent 
requests for this ACB, and this automatic extension can influence 
performance. The VSAM control blocks for the set of strings specified by 
STRNO are allocated on contiguous virtual storage, but this is not guaranteed 
for the strings allocated by dynamic extension. 
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You could specify for STRNO the total number of request parameter lists or 
chains of request parameter lists that you are using to define requests. 
(VSAM needs to remember only one position for a chain of request 
parameter lists.) However, each position beyond the minimum number that 
VSAM needs to be able to remember requires additional virtual storage space 
for: 

• A minimum of one data I/O buffer and, for keyed access, one index I/O 
buffer (the size of an I/O buffer is the control-interval size of a data set) 

• Internal control blocks and other areas 



Example: ACB Macro 



In this example, the ACB macro is used to identify a data set to be opened 
and to specify the types of processing to be performed. The access-method 
control block generated by this example is built when the program is 
assembled. 



BLOCK ACB AM=VSAM , BUFND=4 , 
BUFNI=3, 
BUFSP= 19456, 
DDNAME=DATASETS , 
EXLST=EXITS, 
MACRF=(KEY,DIR, 
SEQ,OUT), 
PASSWD=FIELD, 
STRNO=2 

FIELD DC FL1 '6' ,C CHANGE' 



BLOCK gives symbolic address of the 
access-method control block. 



The update password: CHANGE has 6 
characters. 



The ACB macro's operands are: 

. BUFND, BUFNI, and BUFSP, which specify four I/O buffers for data; 
three I/O buffers for index entries; and 19,456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and control intervals of index entries that are 1024 bytes.. 

• DDNAME, which specifies that this access-method control block is 
associated with a DD statement named DATASETS. 

• EXLST, which specifies that the exit list associated with this 
access-method control block is named EXITS. 

• MACRF, which specifies keyed-direct and keyed-sequential processing for 
both insertion and update. 

• PASSWD, which specifies the location, FIELD, of the password provided. 
FIELD contains the length of the password as well as the password itself. 

• STRNO, which specifies that two requests will require concurrent 
positioning. 
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EXLST Macro (Generate an Exit List) 



The EXLST macro is used to generate an exit list when the program is 
assembled. See the chapter "User- Written Exit Routines" for a description of 
the exit routines. The EXLST macro is coordinated with the EXLST operand 
of an ACB or GENCB macro used to generate an ACB: you must code the 
EXLST operand to make use of the exit list. One or more access-method 
control blocks may use the same exit list — the exit routines indicated by the 
list would do the exit processing for the data sets identified by the control 
blocks. 

Values for EXLST macro operands can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

The format of the EXLST macro is: 



[label] 


EXLST 


[AM=VSAM] 

[,EODAD=(a</</rm [,A | N][,L])] 
[,JKNAD=(address [,A | N][,L])] 
[,LERAD=(address [,A | N][,L])] 
[,SYNAD=(address [,A | N][,L])] 



where: 

label 

is one to eight characters that provides a symbolic address for the exit list 
that is established. 

AM=VSAM 

specifies that the access method using the control block is VSAM. 

[EODAD=( address [,A | N][,L])] 
[,JRNAD=( address [,A | N][,L])] 
[,LERAD=( address [,A | N][,L])] 
[,SYNAD=( address [,A | N][,L])] 

specify that you are supplying a routine for the exit specified. The exits and 

values that can be specified for them are: 

EODAD 

specifies that an exit is provided for special processing when the end of 
a data set is reached by sequential access. 

JRNAD 

specifies that an exit is provided for journalizing as you process data 
records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 

SYNAD 

specifies that an exit is provided for analyzing physical errors. 

address 

is the address of a user-supplied exit routine. The address must 
immediately follow the equal sign. 

A|N 

specifies that the exit routine is active (A) or not active (N). VSAM 
does not enter a routine whose exit is marked not active. 
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Example: EXLST Macro 



L 

specifies that the address is the address of an eight-byte field that 
contains the name of an exit routine in a partitioned data set that is 
identified by a JOBLIB or STEPLIB DD statement or in 
SYS1.LINKLE8. VSAM is to load the exit routine for exit processing. If 
L is omitted, the address gives the entry point of the exit routine in 
virtual storage. L may precede or follow the A or N specification. 



In this example, an EXLST macro is used to identify exit routines that are 
provided for analyzing logical and physical errors. The label, EXITS, of the 
EXLST macro is used in an ACB or GENCB macro that generates an 
access-method control block to associate the exit list with an access-method 
control block. The exit list generated by this example is built when the 
program is assembled. 

EXITS EXLST EODAD=( ENDUP, N ) , EXITS gives symbolic address of the 

LERAD=LOGICAL , exit list. 
SYNAD=(ROUTNAME, 
L) 

ENDUP EODAD routine. 

LOGICAL LERAD routine. 

ROUTNAME DC C ' PHYS I CAL ' Pad shorter names with blanks: 

C'SYN ' or CL8'SYlsr. 

The EXLST macro's operands are: 

• EODAD, which specifies that the end-of-data routine is located at ENDUP 
and is not active. 

• LERAD, which specifies that the logical-error routine is located at 
LOGICAL and is active. 

• SYNAD, which specifies that the physical-error routine's name is located 
at ROUTNAME. 



RPL Macro (Generate a Request Parameter List) 



After you have connected your program to the data set, you can issue 
requests for access to it. A request parameter list defines a request. Each 
request macro (GET, PUT, ERASE, POINT, CHECK, and ENDREQ) gives 
the address of the request parameter list that defines it. See the chapter 
"Request Macros" for information on these macros. 

The RPL macro can be used to generate a request parameter list when your 
program is assembled. The operands of the RPL macro are optional in some 
cases, but required in others. It is not necessary to omit operands that are not 
required for a request; they are ignored. Thus, for example, If you switch from 
direct to sequential retrieval with a request parameter list, you don't have to 
zero out the address of the field containing the search argument 
(ARG= address). 

Values for RPL-macro operands can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

Request parameter lists can be linked together in a chain. A request macro 
points to the first request parameter list, which points to the second, and so 
on. The effect of chaining request parameter lists is to cause a single request 
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macro to operate on multiple records. For example, if a GET macro points to 
a chain of five request parameter lists, five records can be retrieved with a 
single GET. 

The format of the RPL macro is: 



[label] 


RPL 


[ACB= address] 

[,AM=VSAM] 

[,AREA= address ] 

[,AREALEN= number ] 

[,ARG= address] 

[,ECB= address] 

[,KEYLEN= number] 

[,MSGAREA= address ] 

[,MSGLEN= number ] 

[,NXTRPL= address] 

[,OPTCD=([ADR | CNV | KEY] 
[,DIR | SEQ | SKP] 
[,ARD | LRD] 
[,FWD | BWD] 
[,ASY | SYN] 
[,NSP | NUP | UPD] 
[,KEQ | KGE] 
[,FKS | GEN] 
[,LOC | MVE])] 

[,RECLEN= number] 

[,TRANSID= number] 



where: 

label 

is one to eight characters that provides a symbolic address for the request 
parameter list that is generated. You can use it in the request macros to 
give the address of the list. You can use it in the NXTRPL operand of the 
RPL macro, when you are chaining request parameter lists, to indicate the 
next list. 

ACB =address 

specifies the address of the access-method control block that identifies the 
data set to which access will be requested. If you used the ACB macro to 
generate the control block, you may specify the label of that macro for the 
address. If the ACB operand is not coded, you must specify the address 
before issuing the request. 

AM=VSAM 

specifies that the access method using the control block is VSAM. 

AREA=address 

specifies the address of a work area to and from which VSAM moves a 
data record if you request it to do so (with the RPL operand 
OPTCD=MVE). If your request is to process records in the I/O buffer 
(OPTCD=LOC), VSAM puts into this work area the address of a data 
record within the I/O buffer. 
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AREALEN=number 

specifies the length, in bytes, of the work area whose address is specified 
by the AREA operand. Its minimum for OPTCD=MVE is the size of a 
data record (of the largest data record, for a data set with records of 
variable length). For OPTCD=LOC the area should be 4 bytes to contain 
the address of a data record within the I/O buffer. 

ARG=address 

specifies the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For keyed access 
(OPTCD=KEY), the search argument is a full or generic key or relative 
record number; for addressed access (OPTCD=ADR), it is an RBA. If 
you specify a generic key (OPTCD=GEN), you must also specify in the 
KEYLEN operand how many of the bytes of the full key you are using for 
the generic key. 

ECB=address 

specifies the address of an event control block (ECB) that you may supply. 
VSAM indicates in the ECB whether a request is complete or not (using 
standard OS/VS completion codes, which are described in OS/VS1 
System Data Areas and OS/VS 2 Data Areas). This operand is always 
optional. 

KEYLEN=number 

specifies the length, in bytes, of the generic key (OPTCD=GEN) you are 
using for a search argument (given in the field addressed by the ARG 
operand). This operand is specified as a number from 1 through 255; it is 
required when the search argument is a generic key. For full-key searches, 
VSAM knows the key length, which is taken from the catalog definition of 
the data set when you open the data set. 

MSGAREA=address 

specifies the address of an area that you may optionally supply for VSAM 
to send you a message in case of a physical error. The format of a 
physical-error message is given under "Physical Errors" in the chapter 
"Request Macros." 

MSGLEN=nw/wfo?r 

specifies the size, in bytes, of the message area indicated in the 
MSGAREA operand. If MSGAREA is specified, MSGLEN is required. 
The size of a message is 128 bytes; if you provide less than 128 bytes, no 
message is returned to your program. 

NXTKPL=address 

specifies the address of the next request parameter list in a chain. Omit this 
operand from the macro that generates the last list in the chain. When you 
issue a request that is defined by a chain of request parameter lists, indicate 
in the request macro the address of the first parameter list in the chain. 
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OPTCD=([ADR | CNV | KEY ] 
[,DIR | SE£ I SKP] 
[, ARP | LRD] 
[,FWD | BWD] 

[,ASY | SYN ] 

[,NSP | NUP | UPD] 

[, KEQ | KGE] 

[,FKS | GEN] 

[,LOC | MVE ]) 
specifies the options that govern the request defined by the request 
parameter list. Each group of options has a default; options are shown in 
Figure 7 with defaults underlined. Only one option from each group can be 
specified. Some requests do not require an option from all of the groups to 
be specified. The groups that aren't required are ignored; thus, you can use 
the same request parameter list for a combination of requests (GET, PUT, 
POINT, for example) without zeroing out the inapplicable options each 
time you go from one request to another. 

RECLEN=nwmfo?r 

specifies the length, in bytes, of a data record being stored. This parameter 
is required for a PUT request. 

For GET requests, VSAM puts the length of the record retrieved in this field 
in the request parameter list. It will be there if you update and store the 
record. 

TRANSID =number 

specifies a number that relates modified buffers in a buffer pool. Used in 
shared resource applications and described in OS/VS Virtual Storage 
Access Method (VSAM) Options for Advanced Applications. 

You can use the ECB to determine that an asynchronous request is complete 
before issuing a CHECK macro. (If you issue a CHECK before a request is 
complete, you give up control and must wait for completion.) You can also 
test for completion with the TESTCB I/O = COMPLETE operand. TESTCB 
is described later in this chapter. 

Each request parameter list in a chain should have the same OPTCD options. 
Having different options may cause logical errors. You can't chain request 
parameter lists for updating or deleting records — only for retrieving records 
or storing new records. You can't process records in the I/O buffer with 
chained request parameter lists. (OPTCD=UPD and LOC are invalid for a 
chained request parameter list.) 

With chained request parameter lists, a POINT, a sequential or 
skip-sequential GET, or a direct GET with positioning requested 
(OPTCD=NSP) causes VSAM to position itself at the record following the 
record identified by the last request parameter list in the chain. 
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Option Meaning 

ADR Addressed access to a key-sequenced or an entry-sequenced data set: RBAs are 

used as search arguments and sequential access is done by entry sequence 
CNV Control-interval access (this type of access is described in OS/VS Virtual Storage 

Access Method (VSAM) Options for Advanced Applications) 
KEY Keyed access to a key-sequenced or relative record data set: keys or relative record 

numbers are used as search arguments and sequential access is done by key or 

relative record number sequence 

DIR Direct access to a key-sequenced, entry-sequenced, or relative record data set 
SEQ Sequential access to a key-sequenced, entry-sequenced, or relative record data set 
SKP Skip sequential access to a key-sequenced or a relative record data set: used with 
keyed access only 

ARD User's argument determines record to be located, retrieved, or stored 
LRD Last record in the data set is to be located (POINT) or retrieved (GET direct); 
requires OPTCD*BWD 

FWD Processing to proceed in forward direction 

BWD Processing to proceed in backward direction; for keyed (KEY) or addressed (ADR) 
sequential (SEQ) or direct (DIR) requests; valid for POINT, GET, PUT, and 
ERASE operations; establish positioning by a POINT with OPTCD=BWD or by a 
GET direct with OPTCD=NSP 

ASY Asynchronous access; VSAM returns to the processing program after scheduling a 
request so the program can do other processing while the request is being carried 
out 

SYN Synchronous access; VSAM returns to the processing program after completing a 
request 

NSP With OPTCD=DIR only, VSAM is to remember its position (for subsequent 

sequential access); that is, the position is not to be forgotten unless an ENDREQ 

macro is issued 
NUP A data record that is being retrieved will not be updated or deleted; a record that is 

being stored is a new record; VSAM doesn't remember its position for direct 

requests into a work area 
UPD A data record that is being retrieved may be updated or deleted; a record that is 

being stored or deleted was previously retrieved with OPTCD=UPD; VSAM 

remembers its position for sequential and direct requests 

KEQ For GET with OPTCD =(KEY,DIR) or (KEY,SKP) and for POINT with 

OPTCD=KEY, the key (full or generic) that you provide for a search argument 

must equal the key or relative record number of a record 
KGE For the same cases as KEQ, if the key (full or generic) that you provide for a 

search argument doesn't equal that of a record, the request applies to the record 

that has the next higher key 

FKS A full key is provided as a search argument 

GEN A generic key is provided as a search argument; give the length in the KEYLEN 
operand 

LOC For retrieval, VSAM leaves the data record in the I/O buffer for processing; not 
valid for PUT or ERASE; valid for GET with OPTCD=UPD, but to update the 
record, you must build a new version of the record in a work area and modify the 
request parameter list OPTCD from LOC to MVE before issuing a PUT 

MVE For retrieval, VSAM moves the data record to a work area for processing, and for 
storage, VSAM moves it from the work area to the I/O buffer 



Figure 7. OPTCD Options 
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Example: RPL Macro 



In this example, an RPL macro is used to generate a request parameter list 
named PARMLIST. 

ACCESS ACB MACRF= ( SKP , OUT ) , 
DDNAME=PAYROLL 



PARMLIST RPL 


ACB=ACCESS , 
AM=VSAM, 
AREA=WORK, 
AREALEN=125, 
ARG=SEARCH , 






OPTCD=(SKP,UPD) 


Most OPTCD defaults are appropriate 


WORK DS 


CL125 


to assumptions. 


SEARCH DS 


CL8 




MESSAGE DS 


CL128 





The ACB macro, named ACCESS, specifies skip-sequential retrieval for 
update. Further details may be provided on a DD statement named 
PAYROLL. 

The RPL macro's operands are: 

• ACB, which associates the request parameter list with the access-method 
control block generated by ACCESS. 

• AREA and AREALEN, which specify a work area, WORK, that is 125 
bytes long. 

• ARG, which specifies that the search argument is defined at SEARCH. 
The search argument is eight bytes long. 

• MSGAREA and MSGLEN, which specify a message area, MESSAGE, 
that is 128 bytes long. The message area is provided for physical-error 
messages. 

• OPTCD, which specifies skip-sequential processing and specifies that a 
retrieved record may be updated or deleted. 

Because KEYLEN is not coded, a full-key search is assumed. 



GENCB Macro (Generate an Access-Method 
Control Block) 



Before you can open a data set for processing, you must create an 
access-method control block that identifies the data set to be opened, 
specifies the type of processing (for example, sequential processing) to be 
done, specifies basic options (for example, buffer size), and indicates whether 
exit routines are to be used while the data set is being processed. 

The GENCB macro is used to build an access-method control block when the 
program is executed. Generation at execution has the advantage of requiring 
no reassembly of a program when you adopt a new version of VSAM in 
which control block formats might have changed. 
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The operands of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the GENCB request was successful. 

The format of the GENCB macro used to generate an access-method control 
block is: 



[label] 


GENCB 


BLK=ACB 

[,AM=VSAM] 

[,BSTKNO= number] 

[,BUFND= number] 

[,BUFNI= number] 

[,BUFSP= number] 

[,CATALOG=YES | NO] 

[,COPIES= number] 

[,CRA=SCRA | UCRA] 

l,DDNAME=ddname ] 

[,EXLST= address] 

[,LENGTH=number ] 

[,MACRF=([ADR][,CNV][,KEY] 
[,CFX | NFX] 
[,DDN | DSN] 
[,DFR | NDF] 
[,DIR][,SEQ][,SKP] 
[,ICI | NCI] 
[,IN][,OUT] 
[,NIS | SIS] 
[,NRM | ATX] 
[,NRS | RST] 
[,NSR | LSR | GSR] 
[,NUB | UBF])] 

[,MAREA= address] 

[,MLEN= number] 

[,PASSWD= address] 

[,STRNO= number] 

[,WAREA=: address] 



where: 

label 

is one to eight characters that provides a symbolic address for the GENCB 
macro. 

BLK=ACB 

specifies that you are generating an access-method control block. 

AM=VSAM 

specifies that the access method using this control block is VSAM. 
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BSTRNO =number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the object 
being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as 
needed for the access to the base cluster. BSTRNO can also influence 
performance. The VSAM control blocks for the set of strings specified by 
BSTRNO are allocated on contiguous virtual storage, whereas this is not 
guaranteed for the strings allocated by dynamic extension. 

BUFND=number 

specifies the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 1 
plus the number specified for STRNO (if you omit STRNO, BUFND must 
be at least 2, because the default for STRNO is 1). The number can be 
supplied by way of the JCL DD AMP parameter as well as by way of the 
macro. The default is the minimum number required. A larger number for 
BUFND can improve the performance of sequential access. 

BUFNl=number 

specifies the number of I/O buffers VSAM is to use for transmitting index 
entries between virtual and auxiliary storage for keyed access. A buffer is 
the size of a control interval in the index. The minimum number is the 
number specified for STRNO (if you omit STRNO, BUFNI must be at 
least 1, because the default for STRNO is 1). You can supply the number 
by way of the JCL DD AMP parameter as well as by way of the macro. 
The default is the minimum number required. A larger number for BUFNI 
can improve the performance of keyed-direct retrieval. 

BVFSP=number 

specifies the maximum number of bytes of virtual storage to be used for 
the data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• the amount specified in the catalog (BUFFERSPACE), 

• the amount determined from BUFND and BUFNI, or 

• the minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount is less than the minimum amount of 
storage required to process the data set, VSAM cannot open the data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 
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• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not less than the minimum number. Then if required, the 
number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not less than 1 more than the minimum number. Then, if 
required, the number of data buffers is decreased to not less than the 
minimum number. If still required, 1 more is subtracted from the 
number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to less than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. 

CATALOG=YES | NO 

specifies whether a catalog is being opened as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros. When YES is coded, a catalog must be 
processed with an SVC designed for that purpose. 

COPIES=«wm&?r 

specifies the number of copies of the access-method control block VSAM 
is to generate. All of the copies are identical. You can use MODCB to 
tailor each one for the data set and processing you want for it. MODCB is 
described in this chapter. 

CRA=SCRA | UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME=ddname 

is one to eight characters that identifies the data set that you want to 
process by specifying the JCL DD statement for the data set. You may 
omit DDNAME and provide it by way of the MODCB macro before 
opening the data set. MODCB is described later in this chapter. 

EXIjST=address 

specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1. Omitting this operand indicates that you have no 
exit routines. Exit routines are described in the chapter "User- Written Exit 
Routines." 

LENGTH =number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the access-method control block(s). (See the WAREA 
operand.) 
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MACRF=([ADR][,CNV][,KEY] 

[,CFX | NFX ] 

[, DDN | DSN] 

[,DFR|NDF] 

[,DIR][,SE2][,SKP] 

[,ICI | NCI ] 

[,£4][,OUT] 

[,NIS | SIS] 

[,NRM | AIX] 

[,NRS | RST] 

[, NSR | LSR | GSR] 

[,NUB 1 UBF]) 
specifies the kind(s) of processing you will do with the data set. The 
options must be meaningful for the data set. For example, if you specify 
keyed access for an entry-sequenced data set, you cannot open the data 
set. You must specify all of the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
The options are shown earlier in Figure 6; they are arranged in groups, and 
each group has a default value (indicated by underlining). You may specify 
options in any order. You may specify both ADR and KEY to process a 
key-sequenced data set. You may specify both DIR and SEQ; with keyed 
access, you may specify SKP as well. If you specify OUT and want simply 
to retrieve some records as well as update, delete, or insert others, you 
need not also specify IN. 

MAREA=address 

specifies the address of an optional OPEN/CLOSE/TCLOSE message 
area. 

MLEN=number 

specifies the length of an optional OPEN/CLOSE/TCLOSE message 
area. 

PASSWD=address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF operand. The 
first byte of the field contains the length (in binary) of the password 
(maximum of 8 bytes). Zero indicates that no password is supplied. If the 
data set is password-protected and you don't supply a required password in 
the access-method control block, VSAM gives the console operator the 
opportunity to supply it when you open the data set. 

STRNO=numfo?r 

specifies the number of requests requiring concurrent data-set positioning 
VSAM is to be prepared to handle. A request is defined by a given request 
parameter list or chain of request parameter lists. See "RPL Macro 
(Generate a Request Parameter List)" and "GENCB Macro (Generate a 
Request Parameter List)" in this chapter for information on request 
parameter lists. 

V/AREA=address 

specifies the address of an area in which the access-method control 
block(s) is to be generated. (Otherwise VSAM obtains virtual-storage 
space for the area and returns its address to you in register 1 and its length 
in register 0.) The area must begin on a fullword boundary. This operand is 
paired with the LENGTH operand, which must be given if you specify an 
area address. 
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If you did not specify an area in which the access-method control block was 
to be generated, VSAM returns to your program the address of the area 
containing the control block(s) in register 1 and the length of the area in 
register 0. You can find out the length of each control block by dividing the 
length of the area by the number of copies. The address of each control block 
can then be calculated by this offset from the address in register 1. You can 
find the length of an access-method control block with the SHOWCB macro. 
SHOWCB is described later in this chapter. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests for 
virtual storage. 



Example: GENCB Macro (Generate an Access-Method Control Block) 



In this example, a GENCB macro is used to identify a data set to be opened 
and to specify the types of processing to be performed. The access-method 
control block generated by this example is built when the program is 
executed. 



GENCB 



GENCB 



ST 



ACBADDR DS 



FIELD 



DC 



BLK=ACB,AM=VSAM, 

BUFND=4,BUFNI=3, 

BUFSP= 19456, 

DDNAME=DATASETS , 

EXLST=EXITS, 

MACRF=(KEY,DIR, 

SEQ,OUT), 

PASSWD=FIELD, 

STRNO=2 

1 , ACBADDR 



FL1 '6' ,C CHANGE' 



1 copy generated; VSAM gets the 
storage for it, because the WAREA and 
LENGTH operands have been omitted. 



Save the address of the access-method 
control block. 

The address of the access-method 
control block is saved in ACBADDR. 

CHANGE, the password, has 6 
characters. 



The GENCB macro's operands are: 

• BUFND, BUFNI, and BUFSP, which specify four I/O buffers for data; 
three I/O buffers for index entries; and 19,456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and of index entries that are 1024 bytes. 

• DDNAME, which specifies that this access-method control block is 
associated with a DD statement named DATASETS. 

• EXLST, which specifies that the exit list associated with this 
access-method control block is named EXITS. 

• MACRF, which specifies keyed direct and keyed sequential processing for 
both insertion and update. 

• PASSWD, which specifies the location, FIELD, of the password provided. 

• STRNO, which specifies that two requests will require concurrent 
positioning. 
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GENCB Macro (Generate an Exit List) 



The GENCB macro can be used to generate an exit list when the program is 
executed. The GENCB macro is coordinated with the EXLST operand of the 
ACB or GENCB macro used to generate an access-method control block to 
make use of the exit list. One or more access-method control blocks may use 
the same exit list — the exit routines indicated by the list would do all the exit 
processing for the data sets identified by the control blocks. 

The operands of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on return codes used to 
indicate whether the GENCB request was successful. 

The format of the GENCB macro used to generate an exit list is: 



[label] 


GENCB 


BLK=EXLST 

[,AM=VSAM] 

[,EODAD=(address [,A | N][,L])] 
[,JKNAD=(address [,A | N][,L])] 
[,LERAD=(address [,A | N][,L])] 
[,SYNAD=(address [,A | N][,L])] 
[,COPIES= number] 
[,LENGTH= number] 
[,WAREA= address] 



where: 

label 

is one to eight characters that provides a symbolic address for the GENCB 
macro. 

BLK=EXLST 

specifies that you are generating an exit list. 

AM=VSAM 

specifies that the access method using this control block is VSAM. 

[,EODAD=(address [,A | N][,L])] 

[,JKNAD=(address [,A | N][,L])] 

[,LERAD=(address [,A | N][,L])] 

[,SYNAD=(address [,A | N][,L])] 

specify that you are supplying a routine for the exit named. If none of 
these is specified, VSAM generates an exit list with inactive entries for all 
of the exits. The exits and values that can be specified for them are: 

EODAD 

specifies that an exit is provided for special processing when the end of 
a data set is reached by sequential access. 

JRNAD 

specifies that an exit is provided for journalizing as you process data 
records. 
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LERAD 

specifies that an exit is provided for analyzing logical errors. 

SYNAD 

specifies that an exit is provided for analyzing physical errors. 

address 

is the address of a user-supplied exit routine. The address must 
immediately follow the equal sign. 

A|N 

specifies that the exit routine is active (A) or not active (N). VSAM 
does not enter a routine whose exit is marked not active. 

L 

specifies that the address is the address of an eight-byte field that 
contains the name of an exit routine in a partitioned data set that is 
identified by a JOBLIB or STEPLIB DD statement or in 
SYS1.LINKLIB. VSAM is to load the exit routine for exit processing. If 
L is omitted, the address gives the entry point of the exit routine in 
virtual storage. L may precede or follow the A or N specification. 

COPTES=number 

specifies the number of copies of the exit list you want generated. GENCB 
generates as many copies as you specify (default is 1) when your program 
is executed. All of the copies are the same. You can use MODCB to 
change some or all of the addresses in a list. MODCB is described later in 
this chapter. 

LENGTH=number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the exit list(s). (See the WAREA operand.) 

WASEA=address 

specifies the address of an area in which the exit list(s) is to be generated. 
(Otherwise VSAM obtains virtual-storage space for the area and returns its 
address in register 1 and its length in register 0.) The area must begin on a 
fullword boundary. This operand is paired with the LENGTH operand, 
which must be given if you specify an area address. 

If you do not specify an area in which the exit list is to be generated, VSAM 
returns to your program the address of the area in which the exit list(s) is 
generated in register 1, and the length of the area in register 0. You can find 
out the length of each exit list by dividing the length of the area by the 
number of copies. The address of each exit list can then be calculated by this 
offset from the address in register 1. You can find the length of an exit list 
with the SHOWCB macro, described under "SHOWCB Macro (Display an 
Exit List)" later in this chapter. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH) for them enables you to address all of them 
with one base register and to avoid repetitive requests for virtual storage. 
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Example GENCB Macro (Generate an Exit List) 



In this example, a GENCB macro is used to generate an exit list when the 
program is executed. 

EXITS GENCB BLK=EXLST , 

EODAD=(EOD,N), 
LERAD=LOGICAL, 
SYNAD=( ERROR, 
A,L) 



ST 


1 , EXLSTADR 


Address of the exit list is saved 


EOD 




EOD AD routine. 


LOGICAL 




LERAD routine. 


ERROR DC 


C PHYSICAL' 


Name of the SYNAD module. 


EXLSTADR DS 


F 


Save area for exit-list address. 



The GENCB macro's operands are: 

• BLK, which specifies that an exit list is to be generated. 

• EODAD, which specifies that the end-of-data routine is located at EOD 
and is not active. 

• LERAD, which specifies that the logical-error routine is located at 
LOGICAL; because neither A nor N is specified, the LERAD routine is 
marked active by default. 

• SYNAD, which specifies that the physical-error routine's name is located 
at ERROR. 

Because no area was specified in which the exit list was to be generated, 
VSAM obtained virtual storage for the exit list and returned the address in 
register 1. Immediately after the GENCB macro, the address of the exit list, 
contained in register 1, is moved to EXLSTADR. EXLSTADR may be 
specified in a GENCB macro that generates an access-method control block 
or in a MODCB, SHOWCB, or TESTCB macro that modifies, displays, or 
tests fields in an exit list. 



GENCB Macro (Generate a Request Parameter List) 



After you have connected your program to the data set, you can issue 
requests for access to it. A request parameter list defines a request. Each 
request macro (GET, PUT, ERASE, POINT, CHECK, and ENDREQ) gives 
the address of a request parameter list that defines the request. 

The GENCB macro can be used to generate the request parameter list when 
the program is executed. Using the GENCB macro gives you independence 
from possible changes in the format of the request parameter list in future 
releases of VSAM. It also gives you the ability to generate many copies of the 
list. 

If you use GENCB to generate request parameter lists as you need them, and 
later free the space, you should first issue the ENDREQ macro for each 
request parameter list to free the VSAM resources used for keeping track of 
positions in the data set. 

The operands of the GENCB macro to generate a request parameter list are 
optional in some cases, but required in others. It is not necessary to omit 
operands that are not required for a request; they are ignored. Thus, for 
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example, if you switch from direct to sequential retrieval with a request 
parameter list, you don't have to zero out the address of the field containing 
the search argument (ARG=address). 

The operands of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the GENCB request was successful. 

The format of the GENCB macro used to generate a request parameter list is: 



[label] 


GENCB 


BLK=RPL 

[,ACB= address] 

[,AM=VSAM] 

[,AREA= address] 

[,AREALEN= number ] 

[,ARG= address] 

[,COPIES= number] 

[,ECB= address] 

[,KEYLEN= number] 

[,LENGTH= number] 

[,MSGAREA= address ] 

[,MSGLEN= number] 

[,NXTRPL= address] 

[,OPTCD=([ADR | CNV | KEY] 
[,DIR | SEQ | SKP] 
[,ARD | LRD] 
[,FWD | BWD] 
[,ASY | SYN] 
[,NSP|NUP|UPD] 
[,KEQ | KGE] 
[,FKS | GEN] 
[,LOC | MVE])] 

[,RECLEN= number] 

[,TRANSD3= number] 

[,WAREA= address] 



where: 

label 

is one to eight characters that provides a symbolic address for the GENCB 
macro. See the discussion of the COPIES operand for addressing lists 
generated by GENCB. 

BLK=RPL 

specifies that you are generating a request parameter list. 
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ACB =address 

specifies the address of the access-method control block that identifies the 
data set to which access will be requested. If you omit this operand, you 
must issue MODCB to specify the address of the access-method control 
block before you issue a request. MODCB is described later in this 
chapter. 

AM=VSAM 

specifies that the access method using this control block is VSAM. 

AREA=address 

specifies the address of a work area to and from which VSAM moves a 
data record if you request it to do so (with the RPL operand 
OPTCD=MVE). If you request to process records in the I/O buffer 
(OPTCD-LOC), VSAM puts into this work area the address of a data 
record within the I/O buffer. 

AREALEN=wwm&?r 

specifies the length, in bytes, of the work area whose address is specified 
by the AREA operand. Its minimum for OPTCD=MVE is the size of a 
data record (of the largest data record, for a data set with records of 
variable length). For OPTCD=LOC the area should be 4 bytes to contain 
the address of a data record within the I/O buffer. 

ARG=address 

specifies the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For keyed access 
(OPTCD=KEY), the search argument is a full or generic key; for 
addressed access (OPTCD=ADR), it is an RBA. If you specify a generic 
key (OPTCD=GEN), you must also specify in the KEYLEN operand how 
many of the bytes of the full key you are using for the generic key. 

COPIES=m/rofo?r 

specifies the number of copies of the request parameter list you want 
generated. GENCB generates as many copies as you specify (default is 1) 
when your program is executed. 

The copies of a request parameter list can be used to: 

• Chain lists together to gain access to many records with one request. 

• Define many requests to gain access to many parts of a data set 
concurrently. 

All of the copies generated are identical; you have to use MODCB to tailor 
them to specific requests. MODCB is described in this chapter. 

ECB^address 

specifies the address of an event control block (ECB) that you may supply. 
VSAM indicates in the ECB whether a request is complete or not (using 
standard OS/VS completion codes, which are described in OS/VS1 
System Data Areas, and OS/VS2 Data Areas). This operand is always 
optional. 

KEYLEN=/twmfo?r 

specifies the length, in bytes, of the generic key (OPTCD=GEN) you are 
using for a search argument (given in the field addressed by the ARG 
operand). This operand is required with a search argument that is a generic 
key. The number can be 1 through 255. For full-key searches, VSAM 
knows the key length, which is taken from the catalog definition of the 
data set when you open the data set. 
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LENGTH= number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the request parameter list(s). (See the WAREA 
operand.) You can find out how long a request parameter list is with the 
SHOWCB macro, described later in this chapter. 

MSGAREA=address 

specifies the address of an area that you are supplying for VSAM to send 
you a message in case of a physical error. The format of a physical-error 
message is given under "Physical Errors" in the chapter "Request 
Macros." This operand is always optional. 

MSGLEN=number 

specifies the size, in bytes, of the message area indicated in the 
MSGAREA operand. The size of a message is 128 bytes; if you provide 
less than 128 bytes, no message is returned to your program. This operand 
is required when MSGAREA is coded. 

NXTRPL=address 

specifies the address of the next request parameter list in a chain. Omit this 
operand from the macro that generates the only or last list in the chain. 
When you issue a request that is defined by a chain of request parameter 
lists, indicate in the request macro the address of the first parameter list in 
the chain. A single request macro can be defined by multiple request 
parameter lists, such that a GET, for example, can cause VSAM to retrieve 
two or more records. 

OPTCD=([ADR | CNV | KEY ] 
[,DIR | SEQ | SKP] 
[, ARD | LRD] 
[, FWP | BWD] 

[,ASY|SYN] 

[,NSP|NUP|UPD] 

[, KEQ | KGE] 

[, FKS | GEN] 

[,LOC | MVEJ) 
specifies the options that govern the request defined by the request 
parameter list. Each group of options has a default; options are shown 
earlier in Figure 7 with defaults underlined. Only one option from each 
group is effective for a request. Some requests do not require an option 
from all of the groups to be specified. The groups that aren't required are 
ignored; thus, you can use the same request parameter list for a 
combination of requests (GET, PUT, POINT, for example) without 
zeroing out the inapplicable options each time you go from one request to 
another. 

RECLEN=number 

specifies the length, in bytes, of a data record being stored. With 
fixed-length records, set it and forget it. This operand is required for PUT 
requests. For GET requests, VSAM puts the length of the record retrieved 
in this field in the request parameter list. It will be there if you update and 
store the record. 

TRANSID= number 

specifies a number that relates modified buffers in a buffer pool. Used in 
shared resource applications and described in OS/VS Virtual Storage 
Access Method (VSAM) Options for Advanced Applications. 
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WAREA=address 

specifies the address of an area in which the request parameter list(s) is to 
be generated. (Otherwise VSAM obtains virtual-storage space for the area 
and returns its address to you in register 1 and its length in register 0.) The 
area must begin on a fullword boundary. This operand is paired with the 
LENGTH operand, which must be given if you specify an area address. 

If you do not specify an area in which the request parameter list is to be 
generated, VSAM returns to your program the address of the area in which 
the request parameter list(s) was generated in register 1, and the length of the 
area in register 0. You can find the length of each list by dividing the length 
of the area by the number of copies. You can then calculate the address of 
each list by using the length of each list as an offset. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests for 
virtual storage. 

You can use the ECB to determine that an asynchronous request is complete 
before issuing a CHECK macro. (If you issue a CHECK before a request is 
complete, you give up control and must wait for completion.) You can also 
test for completion with the TESTCB I/0=COMPLETE operand. 

When GENCB is used to build a chain of request parameter lists, the request 
parameter lists may be chained using only GENCB macros or using GENCB 
and MODCB macros together. When only GENCB is used, the request 
parameter lists are created in reverse order, as follows: 

SECOND GENCB BLK=RPL 

LR 2,1 

FIRST GENCB BLK=RPL,NXTRPL=( 2 ) 

SECOND GENCB creates the second request parameter list, which makes its 
address available for the first request parameter list. The address of the 
request parameter list is returned in register 1 and is loaded into register 2. 
FIRST GENCB creates the first request parameter list and supplies the 
address of the next request parameter list using register notation. GENCB 
and MODCB macros may be used together to create a chain of request 
parameter lists, as follows: 

GENCB BLK=RPL,COPIES=2 

LR 2,0 

SRL 2 , 1 

LR 3,1 

LA 4,0(2,3) 

MODCB RPL= ( 3 ) , NXTRPL= ( 4 ) 

The GENCB macro creates two request parameter lists. The length of the 
parameter lists is returned in register and loaded into register 2. The address 
of the area in which the lists were created (and, therefore, the address of the 
first one) is returned in register 1 and loaded into register 3. The SRL 
statement divides the total length of the area (register 2) by 2. The LA 
statement loads the address of the second request parameter list into register 
4. The MODCB macro modifies the first request parameter list (register 3) by 
supplying the address of the second request parameter list (register 4) in the 
NXTRPL operand. 

Each request parameter list in a chain should have the same OPTCD options. 
Having different options may cause logical errors. You can't chain request 
parameter lists for updating or deleting records — only for retrieving records 
or storing new records. You can't process records in the I/O buffer with 
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chained request parameter lists. (OPTCD=UPD and LOC are invalid for a 
chained request parameter list.) 

With chained request parameter lists, a POINT, a sequential or 
skip-sequential GET, or a direct GET with positioning requested 
(OPTCD=NSP) causes VSAM to position itself at the record following the 
record identified by the last request parameter list in the chain. 

Example: GENCB Macro (Generate a Request Parameter List) 

In this example, a GENCB macro is used to generate a request parameter list. 

ACCESS GENCB BLK=RPL, 

ACB=ACCESS , 
AM=VSAM, 
AREA=WORK, 
AREALEN=125, 
ARG=SEARCH , 
MSGAREA=MESSAGE , 
MSGLEN=128, 
OPTCD=(SKP,UPD) 



ACCES S ACB MACRF= ( SKP , OUT ) 

WORK DS CL125 

SEARCH DS CL8 

MESSAGE DS CL128 

The GENCB macro's operands are: 

• BLK, which specifies that a request parameter list is to be generated. 

• ACB, which specifies that the request parameter list is associated with a 
data set and processing options identified by ACCESS. 

• AREA and AREALEN, which specify a 125-byte work area to be used for 
processing records. 

• ARG, which specifies the address of the search argument. 

• MSGAREA and MSGLEN, which specify a 128-byte area to be used for 
physical-error messages. 
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MODCB Macro (Modify an Access-Method Control 
Block) 



The MODCB macro can be used to modify the contents of an access-method 
control block. By using MODCB, you don't have to know the format of the 
control block. 

MODCB allows you to tailor access-method control blocks generated with 
the GENCB macro for specific uses. 

The operands of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the MODCB request was successful. 

The format of the MODCB macro used to modify an access-method control 
block is: 



[label] 


MODCB 


ACB= address 

[,BSTRNO= number] 

[,BUFND= number] 

[,BUFNI= number] 

[,BUFSP= number] 

[,CATALOG=YES | NO] 

[,CRA=SCRA | UCRA] 

[,DDNAME=ddname] 

[,EXLST= address] 

[,MACRF=([ADR][,CNV][,KEY] 
[,CFX | NFX] 
[,DDN | DSN] 
[,DFR | NDF] 
[,DIR][,SEQ][,SKP] 
[,ICI | NCI] 
[,IN][,OUT] 
[,NIS | SIS] 
[,NRM | AK] 
[,NRS | RST] 
[,NSR | LSR | GSR] 
[,NUB | UBF])] 

[,MAREA= address] 

[,MLEN= number] 

[,PASSWD= address] 

[,STRNO= number] 



where: 

label 

is one to eight characters that provides a symbolic address for the MODCB 
macro. 
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ACB=address 

specifies the address of the access-method control block to be modified. 
The data set identified by the access-method control block must not be 
opened. A request to modify the access-method control block of an open 
data set will fail. 

The remaining operands represent operands of the ACB macro that can be 
modified. The value specified replaces the value, if any, presently in the 
access-method control block. There are no defaults. See "ACB Macro 
(Generate an Access-Method Control Block)" earlier in this chapter for an 
explanation of these operands. 

If MODCB is used to modify a MACRF option, other options are unaffected, 
except when they are inconsistent. For example, if you specify 
MACRF=ADR in the MODCB and MACRF=KEY is already indicated in 
the control block, both ADR and KEY will now be indicated. But if you 
specify MACRF=UBF in the MODCB and NUB is indicated, only UBF will 
now be indicated. 

If MODCB is used to change the address of an ACB, you must first issue an 
ENDREQ macro. 



Example: MODCB Macro (Modify an Access-Method Control Block) 



In this example, a MODCB macro is used to modify the name of the exit list 
in an access-method control block. 



MODCB ACB=BLOCK, 

EXLST=EGRESS 



BLOCK was generated at assembly. 



MODCB Macro (Modify an Exit List) 

The MODCB macro can be used to modify an exit list. 

The operands of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the MODCB request was successful. 

The format of the MODCB macro used to modify an exit list is: 



[label] 


MODCB 


EXLST= address 

[,EODAD=([address][,A | N][,L])] 
[,JRNAD=([a<tare™][,A | N][,L])] 
[,LERAD=([address][,A | N][,LJ)] 
[,SYNAD=([address][,A | N][,L])] 



where: 

label 

is one to eight characters that provides a symbolic address for the MODCB 
macro. 
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EXLST^address 

specifies the address of the exit list to be modified. You can modify an exit 
list at any time — that is, before or after opening the data set(s) for which 
the list indicates exit routines. You cannot add an entry to an exit list: if 
you generate a list without an EODAD exit, for instance, you cannot later 
modify the list to contain one. 

The remaining operands represent operands of the EXLST macro that can be 
modified or added to an exit list. See "EXLST Macro (Generate an Exit 
List)" earlier in this chapter for an explanation of these operands. 

Example: MODCB Macro (Modify an Exit List) 

In this example, a MODCB macro is used to activate an exit in an exit list. 

MODCB EXLST= ( * , Indirect notation is used to specify the 

EXLSTADR ) , address of the exit list, which was 

EODAD= ( EOD , L , A ) generated at execution. 



EOD DC C * ENDUP ' 

EXLSTADR DS F When the exit list was generated, its 

address was saved here. 

The MODCB macro's operands are: 

• EXLST, which specifies that the address of the exit list to be modified is 
located at EXLSTADR. 

• EODAD, which specifies that the entry for the end-of-data routine is to be 
marked active in the exit list whose address resides at EXLSTADR. The 
name of the end-of-data routine, ENDUP, is located at EOD. 

MODCB Macro (Modify a Request Parameter list) 

The MODCB macro can be used to modify a request parameter list. 

The operands of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the MODCB request was successful. Typical modifications 
to a request parameter list are to change the indication of length of a record 
(RECLEN) when you're processing a data set with variable-length records 
and to change the type of request (OPTCD), such as from direct to sequential 
access or from full-key search argument to generic-key search argument. 



Control Block Macros 73 



The format of a MODCB macro used to modify a request parameter list is: 



[label] 


MODCB 


RPL= address 

[,ACB= address] 

[, ARE A= address] 

[,AREALEN= number ] 

[,ARG= address ] 

[,ECB= address] 

[,KEYLEN= number] 

[,MSGAREA= address ] 

[,MSGLEN= number] 

[,NXTRPL= address] 

[,OPTCD=([ADR | CNV | KEY] 
[,DIR|SEQ| SKP] 
[,ARD | LRD] 
[,FWD | BWD] 
[,ASY|SYN] 
[,NSP|NUP|UPD] 
[,KEQ | KGE] 
[,FKS | GEN] 
[,LOC | MVE])] 

[,RECLEN= number ] 

[,TRANSID= number] 



where: 

label 

is one to eight characters that provides a symbolic address for the MODCB 
macro. 

KPL=address 

specifies the address of the request parameter list to be modified. You may 
not modify an active request parameter list; that is, one that defines a 
request that has been issued but not completed. To modify such a request 
parameter list, you must first issue a CHECK or an ENDREQ macro. 

The remaining operands represent operands of the RPL macro that can be 
modified. The value specified replaces the value, if any, presently in the 
request parameter list. There are no defaults. See "RPL Macro (Generate a 
Request Parameter List)" earlier in this chapter for an explanation of these 
operands. 

If MODCB is used to modify an OPTCD option within a group of options, 
the current option for that group is changed, because only one option in a 
group is effective at a time. 



Example: MODCB Macro (Modify a Request Parameter List) 



In this example, a MODCB macro is used to modify the record-length field in 
a request parameter list. 



L 
MODCB 



3, length 
RPL=( 2 ) , 
RECLEN=( 3 ) 



Load the new record length. 
Register 2 contains the address of the 
request parameter list. Register 3 
contains the record length. 
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The MODCB macro's operands are: 

• RPL, which specifies that register 2 contains the address of the request 
parameter list to be modified. 

• RECLEN, which specifies that the record-length field is to be modified. 
The contents of register 3 will replace any current value in the RECLEN 
field. 



SHOWCB Macro (Display an Access-Method 
Control Block) 



The SHOWCB macro can be used to cause VSAM to move the contents of 
various fields in an access-method control block into your work area. You 
might want to learn the reason for an error or to collect information about a 
data set in order to alter your program logic or print a message or report as a 
result of the examination. 

The operands of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the SHOWCB request was successful. 

The format of the SHOWCB macro used to display fields in an access-method 
control block is: 



[label] 


SHOWCB 


ACB= address 

,AREA= address 

,LENGTH= number 

[,OBJECT=DATA | INDEX] 

,FIELDS=([ACBLEN][,AVSPAC][,BFRFND] 
[,BSTRNO][,BUFND][,BUFNI] 
[,BUFNO][,BUFRDS][,BUFSP] 

[,CENV][,DDNAME][,ENDRBA] 

[,ERROR][,EXLST][,FS] 

[,KEYLEN][,LRECL][,MAREA] 

[,MLEN][,NCIS][,NDELR][,NEXCP] 

[,NEXT][,NINSR][,NBCL][,NLOGR] 

[,NRETR][,NSSS][,NUIW] 

[,NUPDR][,PASSWD][,RKP] 

[,STMST][,STRMAX][,STRNO] 

[,UIW]) 



where: 
label 



is one to eight characters that provides a symbolic address for the 
SHOWCB macro. 
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ACB=address 

specifies the address of the access-method control block whose fields are to 
be displayed. If you used the ACB macro with a label, you can specify the 
label here. The ACB operand is optional when you wish to display the 
length of an access-method control block (FIELDS =ACBLEN). (All 
access-method control blocks have the same length, so you need not 
specify the address of a particular one.) 

AREA=address 

specifies the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS operand. The 
contents of the fields are displayed in the order you specify them. The area 
must begin on a fullword boundary. 

LENGTH=number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. See the FIELDS operand for the 
fields that can be displayed and for the length of each field. If the area is 
not large enough for all of the fields, VSAM doesn't display any of their 
contents and returns an error code indicating it (see "Return Codes from 
the GENCB, MODCB, SHOWCB, and TESTCB Macros" earlier in this 
chapter). 

OBJECT= DATA | INDEX 

specifies whether fields are to be displayed for the data or for the index. 

FIELDS=([ACBLEN] [,AVSPAC][,BFRFND][,BSTRNO] [,BUFND] 
[,BUFNI][,BUFNO][,BUFRDS][,BUFSP] 
[,CINV][,DDNAME][,ENDRBA] 

[,ERROR][,EXLST][,FS] 

[,KEYLEN][,LRECL][,MAREA][,MLEN][,NCIS] 

[,NDELR][,NEXCP][,NEXT] 

[,NINSR][,NIXL][,NLOGR] 

[,NRETR][,NSSS][,NUIW][,NUPDR] 

[,PASSWD][,RKP][,STMST][,STRMAX] 

[,STRNO][,UIW]) 
specifies the fields whose contents are to be displayed. Some of the fields 
can be displayed at any time; others only after a data set is opened. The 
ones that can be displayed only after a data set is opened can, in the case 
of a key-sequenced data set that has been opened for keyed access, pertain 
either to the data or to the index. See the OBJECT operand. Figure 8 
explains the keywords you can code in the FIELDS operand for an 
access-method control block. 
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Key- 
word 



Full- 
words 



Description of the Field 

The following fields can be displayed at any time 

ACBLEN 1 Length of an access-method control block (displaying the length of an 

access-method control block gives your program independence from 
changes in the length that may occur from release to release of 

VSAM) 

BSTRNO 1 Number of strings initially allocated for access to the base cluster by a 

path 

BUFND 1 Number of I/O buffers to be used for data, as specified in the ACB 

(or GENCB) 

BUFNI 1 Number of I/O buffers to be used for index entries, as specified in the 

ACB (or GENCB) 

BUFSP 1 Amount of space specified in the ACB (or GENCB) for I/O buffers 

DDNAME 2 Name of the DD statement that identifies the data set 

ERROR 1 The code returned by VSAM after the opening or closing of the data 

set (see "OPEN Macro" and "CLOSE Macro") 

EXLST 1 Address of the exit list, if any; if none 

MAREA 1 Address of the message area, if any; if none 

MLEN 1 Length of the message area, if any; if none 

PASSWD 1 Address of the field containing the password; the first byte of the field 

contains the length of the password (in binary) 

STRMAX 1 Maximum number of strings concurrently active 

STRNO 1 Number of requests for which VSAM is prepared to remember its 

position in the data set 

Figure 8 (Part 1 of 2). FIELDS Operand Keywords for an Access-Method Control Block 
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Key- 
word 



Fill- 
words 



Description of the Field 

The following fields can be displayed only after the data set is opened 

AVSPAC 1 Amount of available space in the data component or index 

component, in bytes 

BFRFND 1 Number of successful looks-aside 1 

BUFNO 1 Number of I/O buffers actually in use for the data component or 

index component 

BUFRDS 1 Number of buffer reads 1 

CINV 1 Control-interval size for the data component or index component 

ENDRBA 1 Ending RBA of the space used by the data component or index 

component; not the RBA of any record in the data set, but of the last 
used byte in the data set 

FS 1 Percent of free control intervals per control area in the data 

component (0 for OBJECT-INDEX) 

KEYLEN 1 Length of the key of reference of the key field of data records in the 

data component (whether OBJECT-DATA or INDEX) 

LRECL 1 Length of data records in the data component (maximum length for 

variable-length data records) or of index records in the index 
component (control-interval length minus 7) 

NCIS 1 Number of control intervals that have been split in the data 

component (0 for OBJECT-INDEX) 

NDELR 1 Number of records that have been deleted from the data component 

(0 for OBJECT-INDEX) 

NEXCP 1 Number of EXCP macros that VSAM has issued for access to the data 

component or index component since it was opened 

NEXT 1 Number of extents now allocated to the data component or index 

component (the maximum that can be allocated is 123) 

NINSR 1 Number of records that have been inserted into (or added to) the data 

component (0 for OBJECT-INDEX) 

NIXL 1 Number of levels in the index of the data component (0 for 

OBJECT-INDEX) 

NLOGR 1 Number of data records in the data component (0 for 

OBJECT-INDEX) 

NRETR 1 Number of records that have ever been retrieved from the data 

component (0 for OBJECT-INDEX) 

NSSS 1 Number of control areas that have been split in the data component 

(0 for OBJECT-INDEX) 

NUIW 1 Number of writes not initiated by user 1 

NUPDR 1 Number of records in the data component that have ever been 

updated (0 for OBJECT-INDEX) 

RKP 1 Displacement of the key of reference of the key field from the 

beginning of a data record (whether OBJECT-DATA or INDEX) 

STMST 2 System time stamp, which gives the time and day of the last time the 

data component or index component was closed, with bit 51 (counting 
from at the left) equivalent to one microsecond and bits 52 through 
63 unused 

UIW 1 Number of user-initiated writes 1 

described in OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications 

Figure 8 (Part 2 of 2). FIELDS Operand Keywords for an Access-Method Control Block 
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Example: SHOWCB Macro (Display an Access-Method Control Block) 



In this example, a SHOWCB macro is used to display fields in an 
access-method control block. The fields displayed (KEYLEN, LRECL, and 
RKP) permit the program to modify variables to process any one of a number 
of data sets that have different-sized key fields and records and different 
placements of key field in a record. 

SHOWCB ACB=CONTROL, 
AREA=DI SPLAY, 
FIELDS=( KEYLEN, 
LRECL,RKP), 
LENGTH=12 

DISPLAY DS OF Align on fullword boundary. 

KEYLEN DS F 

LRECL DS F 

RKP DS F 

The SHOWCB macro's operands are: 

• ACB, which specifies the address of the access-method control block to be 
displayed. 

• AREA, which specifies that the area to be used to display access-method 
control block fields is to begin on a fullword boundary. 

• FIELDS, which specifies that the KEYLEN, LRECL, and RKP fields are 
to be displayed. 

• LENGTH, which specifies that the length of the area to be used for the 
display is 12 bytes, enough to accommodate the specified fields. 

This display enables the program to set up its variables for the particular data 
set it has opened. 



Example: SHOWCB Macro (Display an Exit List Address) 



In this example, a SHOWCB macro is used to get the address of an exit list by 
displaying the address in an access-method control block that uses the exit 
list. 

SHOWCB ACB=address, 
AREA=address, 
FIELDS=EXLST, 
LENGTH=4 

The SHOWCB macro's operands are: 

• ACB, which specifies the address of an access-method control block from 
which the address of an exit list is to be displayed. 

• AREA and LENGTH, which specify an area and length, four bytes, to be 
used to display the address of the exit list. 

• FIELDS, which specifies that the EXLST field in an access-method control 
block is to be displayed. 
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SHOWCB Macro (Display an Exit list) 

The SHOWCB macro can be used to display fields in an exit list. 

The operands of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the SHOWCB request was successful. 

The format of the SHOWCB macro used to display fields in an exit list is: 



[label] 


SHOWCB 


[EXLST= address,] 
AREA= address 
,LENGTH= number 

,nELDS=([EODADJl,EXLLEN][,JRNAD] 
[,LERAD][,SYNAD]) 



where: 

label 
is one to eight characters that provides a symbolic address for the 
SHOWCB macro. 

AREA=address 

specifies the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS operand. The 
contents of the fields are displayed in the order you specify them. The area 
must begin on a fullword boundary. 

LENGTH=wwmfo?r 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. Each exit-list field requires a 
fullword. If the area is not large enough for all of the fields, VSAM doesn't 
display any of their contents and returns an error code indicating it (see 
"Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter). 

[EXLST=address] 

specifies the address of the exit list whose fields are to be displayed. If you 
used the EXLST macro with a label, you can specify the label here. The 
EXLST operand is optional only when you wish to display the length that 
an exit list can have (see FIELDS=EXLLEN below). 

FIELDS=([EODAD][,EXLLEN][,JRNAD] 

[,LERAD][,SYNAD]) 
specifies the values to be displayed, as follows: 

EODAD 

specifies that the address of the end-of -data-set routine is to be 
displayed. 

EXLLEN 

specifies that the length of the exit list indicated in the EXLST operand 
or if EXLST is omitted, the maximum length an exit length can have, 
is to be displayed. 
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JRNAD 

specifies that the address of the journaling routine is to be displayed. 

LERAD 

specifies that the address of the logical-error analysis routine is to be 
displayed. 

SYNAD 

specifies that the address of the physical-error analysis routine is to be 
displayed. 

You can use SHOWCB to display the address of an exit routine only if the 
exit routine is indicated in the exit list. If it isn't, the SHOWCB request will 
fail. Use TESTCB to test whether an entry for a given exit type is present in 
the exit list and to find out whether the exit is active and whether the routine 
is to be loaded. 



Example: SHOWCB Macro (Display the Length of an Exit List) 



In this example, a SHOWCB macro is used to display the maximum length of 
an exit list. The maximum length of an exit list is subsequently used in a 
GENCB macro to get virtual storage for an exit list. 

SHOWCB AREA=LENGTH , 

FIELDS=EXLLEN, 
LENGTH=4 



L , LENGTH 

GETMAIN R,LV=(0) 

LR 2,1 

GENCB BLK=EXLST , 
LENGTH=( *, 
LENGTH ) , 
WAREA=( 2 ) 



Amount of storage for GETMAIN. 

Address of storage for GENCB. 
Indirect notation for length of work 



LENGTH DS 



Contains the length of GENCB's work 



The SHOWCB macro's operands are: 

• AREA and LENGTH, which specify the area, which begins on a fullword 
boundary, and its length, four bytes, that is to be used for the display. 

• FDELDS, which specifies that the maximum length of an exit list is to be 
displayed. Because only EXLLEN is specified, the EXLST operand is 
omitted. 

The GENCB macro specifies a work area in which an exit list is to be 
generated. The length of the work area is located at LENGTH, where the 
maximum length of an exit list was put as a result of the SHOWCB macro. 
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SHOWCB Macro (Display a Request Parameter list) 

The SHOWCB macro can be used to display fields in a request parameter list. 

The operands of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. See "Return 
Codes from the GENCB, MODCB, SHOWCB, and TESTCB Macros" earlier 
in this chapter for information on the return codes used to indicate whether 
the SHOWCB request was successful. 

The format of the SHOWCB macro used to display fields in a request 
parameter list is: 



[label] 


SHOWCB 


RPL= address 

,AREA= address 

,LENGTH= number 

,nELDS=([ACB][^IXPC][,AREA][,AREALEN] 
[,ARG][,ECB][,FDB1K][,FTNCD] 
[,KEYLEN][,MSGAREA][,MSGLEN 
[,NXTRPL][,RBA][,RECLEN] 
[,RPLLEN][,TRANSID]) 



where: 

label 

is one to eight characters that provides a symbolic address for the 
SHOWCB macro. 

AREA =address 

specifies the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS operand. The 
contents of the fields are displayed in the order you specify them. The area 
must begin on a fullword boundary. 

LENGTH=number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. Each request parameter list field 
requires a fullword. If the area is not large enough for all of the fields, 
VSAM doesn't display any of their contents and returns an error code 
indicating it (see "Return Codes from the GENCB, MODCB, SHOWCB, 
and TESTCB Macros" earlier in this chapter). 

HPL=address 

specifies the address of the request parameter list whose fields are to be 
displayed. If you used the RPL macro with a label, you can specify the 
label here. The RPL operand is optional when you wish to display the 
length of a request parameter list (FIELDS=RPLLEN). (All VSAM 
request parameter lists have the same length, so you need not specify the 
address of a particular one.) 
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FIELDS=([ACB][,AIXPC] [,AREA] [,AREALEN] [,ARG] 

[,ECB][,FDBK][,FTNCD][,KEYLEN] 

[,MSGAREA][,MSGLEN] 

[,NXTRPL][,RBA][,RECLEN] 

[,RPLLEN][,TRANSID]) 
specifies the fields whose contents are to be displayed. Figure 9 explains 
the keywords you can code in the FIELDS operand for a request 
parameter list. 



Key- 
word 

ACB 



AIXPC 
AREA 

AREALEN 
ARG 

ECB 

FDBK 



FTNCD 

KEYLEN 

MSGAREA 

MSGLEN 
NXTRPL 

RBA 

RECLEN 

RPLLEN 
TRANSID 



Full- 
words Description of the Field 

1 Address of the access-method control block that relates the request 
parameter list to the data 

Number of alternate-index pointers 

Address of the work area which the program uses to process a data 
record to which access is defined by the request parameter list 

Length of the work area whose address is given in AREA 

Address of the field containing a search argument, if search arguments 
are being used 

Address of an event control block, if any, in which VSAM indicates the 
completion of requests defined by the request parameter list 

The feedback field into which VSAM puts a return code upon 
completion of a request (for asynchronous requests, you must issue a 
CHECK to cause VSAM to put a return code into the feedback field; 
the meaning of the code in this field depends on the contents of register 
15, which indicates whether the request was successful or failed because 
of a logical or physical error — see "Return Codes from the Request 
Macros" in the next chapter) 

Code that describes the function in which a logical or physical error 
occurred; indicates whether the upgrade set may have been modified 
incorrectly by the request 

Length of the search argument, if a generic key is used for a search 
argument 

Address of the area, if any, into which VSAM puts physical-error 
messages 

Length of the message area, if any 

Address of the next request parameter list, if another one is chained to 
this one 

Relative byte address of the most recently processed record; you could 
use it to record the RB As of records that you are retrieving or storing 
sequentially or by key 

Length of the data record, access to which is defined by the request 
parameter list 

Length of a request parameter list 

Number that relates modified buffers in a buffer pool; described in 
OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications 



Figure 9. FIELDS Operand Keywords for a Request Parameter List 
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Example: SHOWCB Macro (Display a Physical-Error Message) 



In this example, a SHOWCB macro is used to display a physical-error 
message. This example assumes that there is no SYNAD routine (or the 
SYNAD exit is inactive), in which case, VSAM returns control to your 
program following the last executable instruction if a physical error occurs. 
Register 15 indicates a physical error (12), and the feedback field in the 
request parameter list contains a code identifying the error; the message area 
contains more details about the error. Register 1 points to the request 
parameter list. 

REQUEST RPL MSGAREA= 
MESSAGES , 
MSGLEN=128 



SHOWCB AREA=MSGADDR, 

FIELDS=MSGAREA, 
LENGTH=4 , 
RPL=REQUEST 

LTR 15,15 

BNZ CHECKO 



CHECKO 



MESSAGES DS 



MSGADDR DS 



CL128 



Display failed. 



For VSAM to give you a detailed 
message about a physical error. 

For displaying the address of the 
message area with SHOWCB. 



The RPL macro in this example provides for a message area, MESSAGES, of 
128 bytes to be used for any physical-error message. 

The SHOWCB macro's operands are: 

• AREA and LENGTH, which specify a four-byte area, MSGADDR, to be 
used for displaying the address of the message area for the associated 
request parameter list. 

• FIELDS, which specifies that the address of the message area is to be 
displayed. 

• RPL, which specifies the name, REQUEST, of the request parameter list 
for which the message-area address is to be displayed. 
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TESTCB Macro (Test an Access-Method Control Block) 



With the TESTCB macro, you can cause VSAM to set the condition code in 
the PSW (program status word) as a result of a comparison between the 
contents of a field that you specify and a value that you specify. Only one 
keyword can be specified each time TESTCB is issued. You might want to do 
this to: 

• Find out whether an action (for example, opening a data set or activating 
an exit) has been done by VSAM or your program 

• Find out what kind of a data set is being processed in order to alter your 
program logic as a result of the test. 

You examine the PSW condition code after issuing a TESTCB macro (and 
examining the return code in register 15). For keywords specified as an option 
or a name, you test for an equal or unequal comparison; for keywords 
specified as an address or a number, you test for an equal, unequal, high, low, 
not-high, or not-low condition. 

VSAM compares A to B, where A is the contents of the field and B is the 
value to which it is to be compared. A low condition means, for example, that 
A is lower than B — that is, that the value in the control block is lower than 
the value you specified. You may specify only one keyword to be tested. 
These keywords are the same as those that can be specified in the SHOWCB 
macro to display fields in an ACB. Fields can be tested at the same time they 
are displayed. If you specify a list of option codes for a keyword (for example, 
MACRF=(ADR,DIR)), each of them must equal the corresponding value in 
the control block for you to get an equal condition. 

Some of the fields can be tested at any time; others only after a data set is 
opened. The ones that can be tested only after a data set is opened can, in the 
case of a key-sequenced data set, pertain either to the data or to the index. 
See the OBJECT operand. 

The operands of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" earlier in this chapter for information on the return codes used to 
indicate whether the TESTCB request was successful. 
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Only one keyword can be specified each time you issue the macro. The 
format of the TESTCB macro used to test a field in an access-method control 
block is: 



[label] 



TESTCB 



ACB= address 
[,ERET= address] 
[,OBJECT=DATA | INDEX] 
,{ATRB=([ESDS][,KSDS][,REPL] 

[,RRDS][,SPAN][,SSWD] 
[,UNQ][,WCK]) | 

CATALOG=YES | NO | 

CRA=SCRA | UCRA | 

MACRF=([ADR][,ADC][,CnC][,CNV] 
[,DDN][,DFR][,DIR][,DSN] 
[,GSR][,ICI][,IN][,KEY] 
[,LSR][,NCI][,NDF][,NFX] 
[,NIS][,NRM][,NRS][,NSR] 
[,NUB][,OUT][,RST][,SEQ] 
[,SIS][,SKP][,UBF])J 

OFLAGS=OPEN | 

OPENOBJ=PATH | BASE | AJX \ 

ACBLEN= number | 

AVSPAC= number \ 

BSTRNO= number \ 

BUFND= number \ 

BUFNI= number \ 

BUFNO= number \ 

BUFSP= number | 

CINV= number | 

DDNAME=ddname \ 

ENDRBA= number | 

ERROR= number | 

EXLST= address | 

FS= number \ 

KEYLEN= number \ 

LRECL= number \ 

MAREA= address \ 

MLEN= number \ 

NCIS= number \ 

NDELR= number \ 

NEXCP= number \ 

NEXT= number | 

NINSR= number \ 

NIXL= number | 

NLOGR= number \ 

NRETR= number \ 

NSSS= number \ 

NUPDR= number \ 

PASSWD= address \ 

RKP= number \ 

STMST= address \ 

STRNO= number] 
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where: 

ACB=address 

specifies the address of the access-method control block whose information 
you want to test. You may omit it only if you're testing the length of an 
access-method control block (ACBLEN= number). (All VSAM 
access-method control blocks have the same length.) 

ERET=address 

specifies the address of a routine that VSAM is to give control if, because 
of an error, it is unable to test for the condition you specify. For example, 
testing AVSPAC in an access-method control block for an unopened data 
set would fail. VSAM indicates in register 15 whether it could do the test 
and, if not, indicates in register the reason it couldn't. (The reasons are 
discussed earlier in this chapter under "Return Codes from the GENCB, 
MODCB, SHOWCB, and TESTCB Macros.") A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself — and not return to 
VSAM. 

OBJECT={ DATA | INDEX} 

specifies whether you want to test a field for data or for index. 

ATRB=([ESDS][,KSDS][,REPL][,RRDS][,SPAN][,SSWD][,UNQ][,WCK]) 
specifies, for an open data set, the attribute that is to be tested for, as 
follows: 

ESDS 

entry-sequenced data set 

KSDS 

key-sequenced data set 

REPL 

some portion of the index is replicated 

RRDS 

relative record data set 

SPAN 

data set contains spanned records 

SSWD 

sequence set is adjacent to the data 

UNQ 

unique keys 

WCK 

write operations for the data set are being verified 

CATALOG=YES | NO 

specifies that a test is to be made to determine, anytime, whether or not the 
access-method control block specifies a catalog data set. 

CRA=SCRA | UCRA 

specifies that a test is to be made to determine, anytime, whether catalog 
recovery area control blocks are to be built in system storage or user 
storage. 
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MACRF=([ADR][,AIX][,CFX][,CNV][,DDN][,DFR] 

[,DIR][,DSN][,GSR][,ICI][,IN][,KEY][,LSR][,NCI] 

[,NDF][,NFX][,NIS][,NRM][,NRS][,NSR][,NUB][,OUT][,RST] 

[,SEQ][,SIS][,SKP][,UBF]) 

specifies that a test is to be made to determine, anytime, what option or 

combination of options is being used for processing. 

OFLAGS=OPEN 

specifies that a test is to be made to determine, after open, whether the 
data set identified by the control block has been opened. 

OPENOBJ=PATH | BASE | AIX 

specifies that a test is to be made to determine, after open, whether an 
opened object is a path, a base cluster, or an alternate index. 

The remaining operands represent fields in an access-method control block 
that can be compared with the value specified. These fields are the same as 
those that can be displayed by using the SHOWCB macro. See Figure 8 for 
an explanation of these fields. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until 
you've had a chance to test it. 



Example: TESTCB Macro (Use an ERET Routine) 



In this example, a TESTCB macro is used to determine whether the data set 
defined by the access-method control block CLOPEN has been opened. An 
ERET routine, which gets control automatically when a test: is unsuccessful, is 
provided. 

Is the data set open? 



TESTCB ACB=CLOPEN, 
ERET=ERROR, 
OFLAGS=OPEN 



BNE 



UNOPEN 



OPEN 

UNOPEN 

ERROR 



Go to routine for an unopen data set. 

Answer to test question was yes. 

Answer to test question was no. 

An ERET routine to analyze any failure 
of VSAM to carry out the test — same 
routine could serve other TESTCBs. 
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Example: TESTCB Macro (Test for Data-Set Attributes) 



In this example, a TESTCB macro is used to determine whether a data set is a 
key-sequenced or an entry-sequeneed data set. 



LIST 



RPL 



SHOWCB 


AREA=DATAFACT , 




FIELDS=ACB, 




LENGTH=4 , 




RPL=LIST 


LTR 


15,15 


BNZ 


CHECKO 


TESTCB 


ACB=( *, 




DATAFACT ) , 




ATRB=KSDS , 




ERET=CHECKO 


BE 


KEYSEQ 


KEYSEQ 
CHECKO 




DATAFACT DS 


F 



Is the data set key-sequenced? 



Yes. 



Data set is key sequenced. 
Display or test failed. 



For displaying address of 
access-method control block. 



The SHOWCB macro's operands are: 



• AREA and LENGTH, which specify a four-byte area, DATAFACT, 
aligned on a fullword boundary, to be used for the display. 

• FIELDS and RPL, which specify that the address of the access-method 
control block in the LIST request parameter list is to be displayed. 

The TESTCB macro's operands are: 

• ACB, which specifies that a field in the access-method control block, the 
address of which is located at DATAFACT, is to be tested. The SHOWCB 
macro put the address of the access-method control block at DATAFACT. 

• ATRB, which specifies that the access-method control block is to be tested 
to determine whether it is a key-sequenced data set. 

• ERET, which specififies that a routine named CHECKO is to be given 
control if an error occurs that makes it impossible to make the test. 

There is no need to examine the feedback field in an EODAD routine because 
it can be assumed to contain the end-of -data-set indication. 
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TESTCB Macro (Test an Exit List) 

The TESTCB macro can be used to test fields in an exit list. 

The operands of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

The format of the TESTCB macro used to test fields in an exit list is: 



[label] 


TESTCB 


EXLST= address 

[,ERET= address] 

,EODAD={0 | ([address]^ | N][,L])} | 
JRNAD={0 | ([address][,A | N][,L])} | 
LERAD={0 | ([address ][,A | N][,L])} | 
SYNAD={0 | ([address]^ | N][,L])} 

[,EXLLEN= number] 



where: 

label 

is one to eight characters that provides a symbolic address for the TESTCB 
macro. 

EXLST=address 

specifies the address of the exit list whose information you want to test. 
You may omit it only if you're testing the maximum length of an exit list 
(EXLLEN=number). 

ERET=address 

specifies the address of a routine that VSAM is to give control if, because 
of an error, it is unable to test for the condition you specify. For example, 
testing AVSPAC in an access-method control block for an unopened data 
set would fail. VSAM indicates in register 15 whether it could do the test 
and, if not, indicates in register the reason it couldn't. (The reasons are 
discussed earlier in this chapter under "Return Codes from the GENCB, 
MODCB, SHOWCB, and TESTCB Macros.") A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself — and not return to 
VSAM. 

EODAD={0 | ([address][ t A | N][,L])} | 

JRNAD= {0 | ([address ][,A | N][,L])} | 

LERAD={0 | ([address ][,A | N][,L])} | 

SYNAD={0 | ([address][ t A | N][,L])} 

specifies the exit about which you are asking a yes-no question. If you code 
more than one operand for an exitname, each of them must equal the 
corresponding value in the control block for you to get an equal condition. 
The values that can be tested are: 







specifies that a test is to be made to determine whether an entry is 
provided for the exit in the exit list. 
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address 

specifies that a test is to be made to determine whether this is the 
address of the exit. Tests for an address result in an equal, unequal, 
high, low, not-high, or not-low condition. Tests for a combination of an 
address and A, N, or L result in an equal or unequal condition. 

A|N 

specifies that a test is to be made to determine whether an exit is active 
(A) or not active (N). Tests for A or N result in an equal or unequal 
condition. 

L 

specifies that a test is to be made to determine whether the address is 
the location of an 8-byte field containing the name of a module to be 
loaded rather than the entry point of the routine. Tests for L result in an 
equal or unequal condition. 

EXLLEN =number 

specifies either the maximum length that an exit list can have (if you don't 
code the EXLST operand) or the actual length of the exit list indicated by 
the EXLST operand. If you specify an exit, you may not also specify 
EXLLEN; if you specify EXLLEN, you may not also specify an exit. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until 
you've had a chance to test it. 



Example: TESTCB Macro (Use a Branch Table) 



In this example, a TESTCB macro is used to test whether ENDPROC is the 
routine supplied for the EODAD exit in the exit list EXITS, and whether the 
EODAD exit is active. A branch table is used to determine whether the test is 
successful. 

TESTCB EODAD= ( ENDPROC , Is ENDPROC supplied and is the exit 

A ) , EXLST=EXITS active? 

B *+4(15) 

If the test was made successfully, register 1 5 
contains and the next instruction is executed. 

B TEST1 

If it was unsuccessful, register 15 contains 4 and 
the next instruction is executed. 



Yes, ENDPROC is supplied and active. 

ENDPROC isn't supplied, or the exit 
isn't active. 





ABEND 


2 , DUMP 


TEST1 


BNE 


NO 


YES 


. . . 




NO 
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TESTCB Macro (Test a Request Parameter List) 

The TESTCB macro can be used to test fields in a request parameter list. 

The operands of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. "Appendix C: Operand 
Notation for GENCB, MODCB, SHOWCB, and TESTCB" gives all the ways 
of coding each operand for the macros that work at execution. 

See "Return Codes from the GENCB, MODCB, SHOWCB, and TESTCB 
Macros" for information on the return codes used to indicate whether the 
TESTCB request was successful earlier in this chapter. 

The format of the TESTCB macro to test fields in a request parameter list is: 



[label] 


TESTCB 


RPL= address 
[,ERET= address] 
{AIXFLAG=AIXPKP | 
AIXPC= number \ 
FTNCD= number \ 
I/0=COMPLETE | 
OPTCD=([ADR][,ARD][ASY][,BWD] 
[,CNV][,DIR][,FKS][,FWD] 
[,GEN][,KEQ][,KEY][,KGE][,LOC] 
[,LRD][,MVE][,NSP][,NUP][,SEQ] 
[,SKP][,SYN][,UPD]) | 

ACB= address | 

AREA= address | 

AREALEN= number \ 

ARG= address \ 

ECB= address \ 

FDBK= number \ 

KEYLEN= number \ 

MSGAREA= address \ 

MSGLEN= number \ 

NXTRPL= address \ 

RBA= number \ 

RECLEN= number | 

RPLLEN= number \ 

TRANSID= number } 



where: 

label 

is one to eight characters that provides a symbolic address for the TESTCB 
macro. 

KPL=address 

specifies the address of the request parameter list whose information you 
want to test. You may omit it only if you're testing the length of a request 
parameter list (RPLLEN=number). (All request parameter lists have the 
same length.) 
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EKET=address 

specifies the address of a routine that VSAM is to give control if, because 
of an error, it is unable to test for the condition you specify. For example, 
testing AVSPAC in an access-method control block for an unopened data 
set would fail. VSAM indicates in register 15 whether it could do the test 
and, if not, indicates in register the reason it couldn't. (The reasons are 
discussed earlier in this chapter under "Return Codes from the GENCB, 
MODCB, SHOWCB, and TESTCB Macros.") A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself — and not return to 
VSAM. 

AIXFLAG=AIXPKP 

specifies that prime-key pointers are used rather than RBAs. 

AIXPC= number 

specifies the pointer count. 

FTNCD= number 

specifies whether the upgrade set is correct or may have been modified by 
a request. These codes are described under "Function Codes" in the 
chapter "Request Macros." 

IO=COMPLETE 

specifies that a test is to be made to determine whether an asynchronous 
request has been completed. (When you issue a CHECK macro, you 
suspend processing until a request has been completed if it hasn't yet been 
completed.) 

OPTCD=([ADR][,ARD][,ASY][,BWD][,CNV][,DIR][,FKS][,FWD] 

[,GEN][,KEQ][,KEY][,KGE][,LOC][,LRD][,MVE][,NSP] 

[,NUP][,SEQ][,SKP][,SYN][,UPD]) 
specifies that a test is to be made to determine what option or combination 
of options is being used for the request. 

The remaining operands specify fields in a request parameter list and values; 
the contents of a field are to be compared to the specified value. These fields 
are the same as those that can be displayed by using a SHOWCB macro. See 
Figure 9 under "SHOWCB Macro (Display a Request Parameter List)" for 
an explanation of these fields. Fields can be tested at the same time they are 
displayed. 

You may specify only one keyword. If you code a list of option codes (for 
example, OPTCD=(KEY,DIR)), each of them must equal the corresponding 
value in the control block for you to get an equal condition. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until 
you've had a chance to test it. Examples of using an ERET routine and using 
a branch table are given at the end of the section. 
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Example: TESTCB Macro (Test a Request Parameter List) 



TESTCB RPL=(3), 
RECLEN=80 



BE 



NOCHNGE 



CHANGE 



NOCHNGE 



Because the record length in the request 
parameter list was not 80, the length 
indicator must be modified so that it is 
80. 

Because the record length in the request 
parameter list was 80, no change is 
required. 



The TESTCB macro's operands are: 

• RPL, which specifies that the address of the request parameter list to be 
tested is contained in register 3. 

• RECLEN, which specifies that the record length indicated in the request 
parameter list is to be tested to determine whether it is 80. 
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REQUEST MACROS 



This chapter describes the macro instructions that cause some action to be 
taken regarding data or processing. The request macros are: 

• GET, which causes a record to be retrieved. 

• PUT, which causes a record to be stored. 

• ERASE, which causes a record previously retrieved for update to be 
deleted from a key-sequenced data set. 

• POINT, which causes VSAM to position at the desired record. 

• CHECK, which causes processing to be suspended to await the completion 
of some event. 

• ENDREQ, which causes a specified request to be terminated. 

GETIX and PUTIX, which cause an index record to be retrieved and stored, 
are described in OS/VS Virtual Storage Access Method (VSAM) Options 
for Advanced Applications. 

Each request macro makes use of a request parameter list; the request 
parameter list defines the action to be taken. For example, when a GET 
macro points to a request parameter list that specifies synchronous, sequential 
retrieval, the next record in sequence is retrieved. When an ENDREQ macro 
points to a request parameter list, any current request (for example, a PUT) 
for that request parameter list is ended immediately. 

A return code in register 15 and a code in the feedback field of the request 
parameter list indicate what happened as a result of a request macro. The 
return codes in register 15, feedback-field codes, and the request macros are 
described below. 



Return Codes from Request Macros 



After you issue a request macro for access to data or a CHECK or ENDREQ 
macro, register 15 contains a return code. The meaning of the return code 
depends on whether processing is asynchronous or synchronous. 

After you issue an asynchronous request for access to a data set, VSAM 
indicates in register 15 whether the request was accepted, as follows: 

Reg. 15 Condition 

Request was accepted. 

4 Request was not accepted because the request parameter list indicated by the 

request (RPL=*address) was active for another request. 

If the asynchronous request was accepted, you issue a CHECK after doing 
your other processing so VSAM can indicate in register 15 whether the 
request was completed successfully, set a return code in the feedback field, 
and exit to any appropriate exit routine. If the request was not accepted, you 
should either wait until the other request is complete (for example, by issuing 
a CHECK on the request parameter list) or terminate the other request (using 
ENDREQ). Then you can reissue the rejected request. 
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Feedback-Field Codes 



After a synchronous request, or a CHECK or ENDREQ macro, register 15 
indicates whether the request was completed successfully, as follows: 

Reg. 15 Condition 

Request completed successfully. 

4 Request was not accepted because the request parameter list indicated by the 

request (RPL= address) was active for another request. 

8 Logical error; specific error is indicated in the feedback field in the RPL. 

12 Physical error; specific error is indicated in the feedback field in the RPL. 



Paired with the 0, 8, and 12 indicators in register 15 are codes in the feedback 
field of the request parameter list. The feedback codes for the 0, or 
successful, indicator in register 15, which doesn't cause VSAM to exit to an 
exit routine, are: 



FDBK 
Code 



4 



8 
12 



Condition 

Request completed successfully. 

Request completed successfully. For retrieval, VSAM mounted another volume 
to locate the record; for storage, VSAM allocated additional space or mounted 
another volume. 

Duplicate key follows. 

Write-buffer suggested (shared resources only). 



You can examine the feedback field of the request parameter list with the 
SHOWCB or TESTCB macro. You may code your examination routine 
immediately following the request macro. However, logical errors, physical 
errors, and reaching the end of the data set all cause VSAM to exit to the 
appropriate exit routine, if you provide it. 

Coordinate error checking in your program with your error-analysis exit 
routines. If they terminate the program, for instance, you would not need to 
code a check for an error after a request. But if a routine returns to VSAM to 
continue processing, you might check register 15 after a request to determine 
whether there was an error. Even though the error was handled by an exit 
routine, you may want to modify processing in light of the error. 
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Function Codes 



Logical Errors 



When a logical or physical error occurs, VSAM provides a code that identifies 
the function being attempted when the error occurred and indicates whether 
the alternate-index upgrade set is correct following the request that failed. 
The function code can be displayed and tested by the SHOWCB and 
TESTCB macros. The codes and their meanings are: 
Code Function Upgrade Set Status 



X'OO' 


An attempt to access the 
base cluster 


Correct 


xw 


An attempt to access the 
base cluster 


May be incorrect 


X*02' 


An attempt to access the 
alternate index over a 
base cluster 


Correct 


X'03' 


An attempt to access the 
alternate index over a 
base cluster 


May be incorrect 


X'04' 


Upgrade processing 


Correct 


X'05' 


Upgrade processing 


May be incorrect 



If a logical error occurs and you have no LERAD routine (or the LERAD exit 
is inactive), VSAM returns control to your program following the last 
executed instruction. Register IS indicates a logical error (8), and the 
feedback field in the request parameter list contains a code identifying the 
error. Register 1 points to the request parameter list. Figure 10 gives the 
logical-error return codes in the feedback field and explains what each one 
means. 
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FDBK 

Code 



8 
12 



16 
20 

24 
28 



32 

36 

40 
44 
64 

68 

72 

76 

80 

84 

88 

92 

96 
100 



Condition 

End of data set encountered (during sequential or skip-sequential retrieval), or 
the search argument is greater than the high key of the data set. Either no 
EOD AD routine is provided, or one is provided and it returned to VSAM and 
the processing program issued another GET. 

You attempted to store a record with a duplicate key, or there is a duplicate 
record for an alternate index with the unique key option. 

You attempted to store a record out of ascending key sequence in skip-sequential 
mode; record had a duplicate key; for skip-sequential processing, your GET, 
PUT, and POINT requests are not referencing records in ascending sequence; 
or, for skip-sequential retrieval, the key requested is lower than the previous key 
requested. For shared resources, buffer pool is full. 

Record not found. 

Record already held in exclusive control by another requester. 

Record resides on a volume that cant be mounted. 

Data set cannot be extended because VSAM can't allocate additional 
direct-access storage space. Either there is not enough space left to make the 
secondary allocation request or you attempted to increase the size of a data set 
while processing with SHROPT-4 and DISP-SHR. 

You specified an RBA that doesn't give the address of any data record in the 
data set. 

Key ranges were specified for the data set when it was defined, but no range was 
specified that includes the record to be inserted. 

Insufficient virtual storage in your address space to complete the request. 

Work area not large enough for the data record (GET with OPTCD-MVE). 

As many requests are active as the number specified in the STRNO parameter of 
the ACB macro; therefore, another request cannot be activated. 

You attempted to use a type of processing (output or control-interval processing) 
that was not specified when the data set was opened. 

You made a keyed request for access to an entry-sequenced data set, or you 
issued a GETIX or PUTIX to an entry-sequenced or relative record data set. 

You issued an addressed or control-interval PUT to add to a key-sequenced data 
set, or you issued a control-interval PUT to a relative record data set. 

You issued an ERASE request for access to an entry-sequenced data set, or you 
issued an ERASE request for access to an entry-sequenced data set via a path. 

You specified OPTCD«=LOC for a PUT request or in a request parameter list in 
a chain of request parameter lists. 

You issued a sequential GET request without having caused VSAM to be 
positioned for it, or you changed from addressed access to keyed access without 
causing VSAM to be positioned for keyed-sequential retrieval; there was no 
sequential PUT insert for a relative record data set, or you attempted an illegal 
switch between forward and backward processing. 

You issued a PUT for update or an ERASE without a previous GET for update 
or a PUTIX without a previous GETIX. 

You attempted to change a key while making an update. 

You attempted to change the length of a record while making an addressed 
update. 



Figure 10 (Part 1 of 2). Logical-Error Return Codes in Feedback Field 
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FDBK 

Code Condition 

104 The RPL options are either invalid or conflicting in one of the following ways: 

(1) SKP was specified and either KEY was not specified or BWD was 
specified 

(2) BWD was specified for CNV processing 

(3) FWD and LRD were specified 

(4) Neither ADR, CNV, nor KEY was specified in the RPL 

(5) WRTBFR, MRKBFR, or SCHBFR was issued, but either TRANSID was 
greater than 3 1 or the shared resource option was not specified 

(6) ICI processing was specified, but a request other than a GET or a PUT was 
issued 

108 RECLEN specified was larger than the maximum allowed, equal to 0, or smaller 

than the sum of the length and the displacement of the key field; RECLEN was 
not equal to record (slot) size specified for a relative record data set. 

112 KEYLEN specified was too large or equal to 0. 

116 During initial data-set loading (that is, when records are being stored in the data 

set the first time it's opened), GET, POINT, ERASE, direct PUT, 
skip-sequential PUT, or PUT with OPTCD-UPD is not allowed. For initial 
loading of a relative record data set, the request was other than a PUT insert. 

132 An attempt was made in locate mode to retrieve a spanned record. 

136 You attempted an addressed GET of a spanned record in a key-sequenced data 

set. 

140 Inconsistent spanned record. 

144 Invalid pointer (no associated base record) in an alternate index. 

148 The maximum number of pointers in the alternate index has been exceeded. 

152 Not enough buffers are available to process your request (shared resources 

only). 

192 Invalid relative record number. 

196 You issued an addressed request to a relative record data set. 

200 You attempted addressed or control-interval access through a path. 

204 PUT insert requests are not allowed in backward mode. 

Figure 10 (Part 2 of 2). Logical-Error Return Codes in Feedback Field 
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Physical Errors 



If a physical error occurs and you have no SYNAD routine (or the SYNAD 
exit is inactive), VSAM returns control to your program following the last 
executable instruction. Register 15 indicates a physical error (12), and the 
feedback field in the request parameter list contains a code identifying the 
error; the message area contains more details about the error. Register 1 
points to the request parameter list. Figure 1 1 gives the physical-error return 
codes in the feedback field and explains what each one indicates. 

FDBK 

Code Condition 

4 Read error occurred for a data set. 

8 Read error occurred for an index set. 

12 Read error occurred for a sequence set. 

1 6 Write error occurred for a data set. 

20 Write error occurred for an index set. 

24 Write error occurred for a sequence set. 

Figure 1 1. Physical-Error Return Codes in Feedback Field 

Figure 12 gives the format of a physical-error message. The format and some 
of the contents of the message are purposely similar to the format and 
contents of the SYNAD AF message, which is described in OS/VS Data 
Management Macro Instructions. 



Field 


Bytes 


Length 


Discussion 


Message 
Length 


0-1 


2 


Binary value of 128 




2-3 


2 


Unused (0) 


Message 
Length - 4 


4-5 


2 


Binary value of 

(provided for compatibility with SYNAD AF 

message) 




6-7 


2 


Unused (0) 


Address of 
I/O Buffer 


8-11 


4 


The I/O buffer associated with the data in relation 
to which the error occurred 

The rest of the message is in printable format: 


Date 


12-16 


5 


YYDDD (year and day) 




17 


1 


Comma (,) 


Time 


18-25 


8 


HHMMSSTH (hour, minute, second, and tenths and 
hundredths of a second) 




26 


1 


Comma (,) 


RBA 


27-34 


8 


Relative byte address of the record in relation to 
which the error occurred. 




35 


1 


Comma (,) 


Component 
TYPE 


36-41 


6 


"DATA" or "INDEX" 




42 


1 


Comma (,) 


Volume Serial 
Number 


43-48 


6 


Volume serial number of the volume in relation 
to which the error occurred 




49 


1 


Comma (,) 


Figure 12 (Part 1 of 3). 


Physical-Error Message Format 
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Field 


Bytes 


Length 


Discussion 


Job Name 


50-57 


8 


Name of the job in which error occurred 




58 


1 


Comma (,) 


Step Name 


59-66 


8 


Name of the job step in which error occurred 




67 


1 


Comma (,) 


Unit 


68-70 


3 


The unit, CUU (channel and unit), in relation to 
which the error occurred 




71 


1 


Comma (,) 


Device Type 


72-73 


2 


The type of device in relation to which the error 
occurred (always DA for direct access) 




74 


1 


Comma (,) 


ddname 


75-82 


8 


The ddname of the DD statement defining the data 
set in relation to which the error occurred 




83 


1 


Comma (,) 


Channel 
Command 


84-89 


6 


The channel command that caused the error in the 
first two bytes, followed by "- OP" 




90 


1 


Comma (,) 


Message 


91-105 


15 


Messages are divided according to ECB condition 



codes: 

X'41' "INCORR LENGTH" 
"UNIT EXCEPTION" 
"PROGRAM CHECK" 
"PROTECTION CHK" 
"CHAN DATA CHK" 
"CHAN CTRL CHK" 
"INTFCE CTRL CHK" 
"CHAINING CHK" 
"UNIT CHECK" 

// the type of unit check can be determined, the 'UNIT CHECK' message 
is replaced by one of the following: 

" CMD REJECT' 
" INT REQ" 
"BUS OUT CK" 
"EQP CHECK" 
"DATA CHECK" 
"OVER RUN" 
"TRACK COND CK" 
"SEEK CHECK" 
"COUNT DATA CHK" 
"TRACK OVERRUN' 
"CYLINDER END" 
"INVALID SEQ" 
"NO RECORD FOUND" 
"FILE PROTECT' 
"MISSING AM." 
"OVERFL INCP" 

X'48'— "PURGED REQUEST" 

X*4F'— "R.HA.RO. ERROR" 

For any other ECB completion code— "UNKNOWN 
COND." 
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Figure 12 (Part 2 of 3). 



1 Comma (,) 

Physical-Error Message Format 
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Field 



Bytes Length Discussion 



Physical 107-120 

Direct-Access 

Address 


14 


BBCCHHR (bin, cylinder, head, 
and record) 


121 


1 


Comma (,) 


Access 122-127 
Method 


6 


"VSAM" 



Figure 12 (Part 3 of 3). Physical-Error Message Format 



GET Macro (Retrieve a Record) 



The GET macro is used to retrieve a record. 

The GET macro is used with the PUT macro to update records. See "PUT 
Macro (Store a Record)" later in this chapter for examples that show the use 
of the GET macro to update records. The GET macro is used with the 
ERASE macro to delete records in a key-sequenced or relative record data 
set. See "ERASE Macro (Delete a Record)" later in this chapter for examples 
that show the use of the GET macro to delete records. 

The format of the GET macro is: 



[label] 


GET 


RPL= address 



where: 

label 

is one to eight characters that provides a symbolic address for the GET 
macro. 

RPL= address 

specifies the address of the request parameter list that defines this GET 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. 
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Example; Keyed-Sequential Retrieval 



In this example, a GET macro is used to sequentially retrieve records by key. 
Fixed-length, 100-byte records are moved to a work area. Processing is 
synchronous. 

INPUT ACB MACRF=(KEY, All MACRF and OPTCD options 

SEQ , IN ) specified are defaults and could have 

been omitted. 



RETRVE RPL 



ACB=INPUT, 
AREA=IN, 
AREALEN=100, 
OPTCD=(KEY,SEQ, 
SYN , NUP , MVE ) 



LOOP 



GET 



LTR 
BNZ 



RPL=RETRVE 



15,15 
ERROR 



This GET or identical GETs can be 
issued, with no change in the request 
parameter list, to retrieve subsequent 
records in key sequence. 



ERROR 



LOOP 



Request wasn't accepted or failed. 



IN 



DS 



CL100 



IN contains a data record after GET is 
completed. 



The records are retrieved in key sequence. No search argument has to be 
specified; VSAM is positioned at the first record in key sequence when the 
data set is opened, and the next record is retrieved automatically as each GET 
is issued. The branch to ERROR could also be taken if the end of the data set 
is reached. 



Example: Skip-Sequential Retrieval 



In this example, a GET macro is used to retrieve variable-length records 
synchronously. Records are to be processed in the I/O buffer. The search 
argument is full key, compared greater-than-or-equal; key length is eight 
bytes. 

The records are retrieved in key sequence, but some records are skipped. 
Skip-sequential retrieval is very similar to keyed-direct retrieval, except that 
you must retrieve records in ascending sequence (with skips) rather than in a 
random sequence. 

GENCB BLK=ACB, VSAM gets an area in virtual storage to 

DDNAME= INPUT, generate the access-method control 

MACRF= ( KEY , block and returns the address in register 

SKP,IN) 1. 

LTR 15,15 

BNZ CHECKO 

LR 2,1 
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GENCB BLK=RPL , ACB= ( 2 ) , 
AREA=RCDADDR, 
AREALEN=4, 
ARG=SRCHKEY , 
OPTCD=(KEY,SKP, 
SYN,NUP,KGE,FKS, 
LOC) 

LTR 15,15 
BNZ CHECKO 
LR 3,1 



Address of the request parameter list. 



LOOP 



MVC 



SRCHKEY , source 



GET 


RPL=( 3 ) 


LTR 


15,15 


BNZ 


ERROR 


SHOWCB AREA=RCDLEN, 




FIELDS=RECLEN, 




LENGTH=4,RPL=(3) 


LTR 


15,15 


BNZ 


CHECKO 



Search argument for retrieval, moved in 
from a table or a transaction record. 



Display the length of the record. 



LOOP 



ERROR 
CHECKO 



RCDADDR DS 



Request wasn't accepted or failed. 
Generation or display failed. 



F Work area into which VSAM puts the 

address of a data record within the I/O 
buffer (OPTCD-LOC). 

SRCHKEY DS CL8 Search argument for retrieval. 

RCDLEN DS F For displaying variable record lengths. 

The macros and instructions are described, as follows: 

• The first GENCB generates an access-method control block, which 
specifies keyed, skip-sequential, and input processing. The address of the 
access-method control block is stored in register 2. 

• The second GENCB generates a request parameter list. The address of the 
request parameter list is stored in register 3. 

• MVC moves the search argument into SRCHKEY, the area defined for the 
search argument. 

• GET specifies that the record pointed at by the request parameter list 
whose address is in register 3 is to be retrieved. Records are retrieved by a 
skip-sequential search through the sequence set of the index. 
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Example: Addressed-Sequential Retrieval 



In this example, one GET macro is used to retrieve multiple fixed-length, 
20-byte records. The records are moved to a work area (only option). 

BLOCK ACB DDNAME= INPUT, 

MACRF=(ADR,SEQ, 
IN) 



GENCB 


1 BLK=RPL f 
COPIES=10, 
ACB=BLOCK, 
OPTCD=(ADR,SEQ, 
SYN,NUP,MVE) 




LTR 


15,15 






BNZ 


CHECKO 






LA 


3,10 




Number of lists (10). 


LR 


2,1 




Address of the first list. 


LR 


1,0 




Length of all of the list! 



SR 
DR 

LR 

LR 
LA 



0,0 
0,3 

3,1 

4,2 

5 , RECAREA 



AR 


4,3 


MODCB 


RPL=(2), 




NXTRPL=( 4 ) , 




AREA=( 5 ) , 




AREALEN=20 


LTR 


15,15 


BNZ 


CHECKO 


AR 


2,3 


LA 


5,20(5) 



1 contain length and address of the 
generated control blocks when VSAM 
returns control after GENCB. 

Prepare for following division. 

Divide number of lists into length of all 
of the lists. 

Save the resulting length of a single list 
for an offset. 

Save address of the first list. 

Address of the first work area. 

Do the following six instructions ten 
times to set up all of the request 
parameters lists. The tenth time, 
register 4 must be set to to indicate 
the last request parameter list in the 
chain. 

Address the next list. 

In each request parameter list, indicate 
the address of the next list and the 
address and length of the work area. 



Address the next list. 

Address the next work area. 

Restore register 2 to address the first list 
before continuing to process. 



LOOP 



GET 


RPL=( 2 ) 


LTR 


15,15 


BNZ 


ERROR 



LOOP 



Process the ten records that have been 
retrieved by the GET. 
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CHECKO 
ERROR 



RECAREA DS 



CL200 



Display the feedback field 
(FIELDS-FDBK) of each request 
parameter list to find out which one had 
an error. 

Space for a work area for each of the 
ten request parameter lists. 



The GENCB macro generates ten request parameter lists; the lists are 
subsequently chained together by using the MODCB macro to modify the 
NXTRPL operand in each copy. Because SEQ is specified in each request 
parameter list and no previous request has been issued against the 
access-method control block since it was opened, retrieval begins at the 
beginning of the data set. Each time the GET macro is executed, VSAM is 
positioned at the next record in RBA sequence. VSAM moves each record 
into the work area provided for the request parameter list that identifies the 
record. 

If an error occurred for one of the request parameter lists in the chain and 
you have supplied error-analysis routines, VSAM takes a LERAD or SYNAD 
exit before returning to your program. Register IS is set to indicate the status 
of the request. A code of indicates that no error was associated with any of 
the request parameter lists. Any other code indicates that an error occurred 
for one of the request parameter lists. You should issue a SHOWCB macro 
for each request parameter list in the chain to find out which one had an 
error. VSAM doesn't process any of the request parameter lists beyond the 
one with an error. 
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Example: Keyed-Direct Retrieval 



In this example, a GET macro is used to retrieve fixed-length, 100-byte 
records directly by key. The key length is 15 bytes; the search argument is a 
five-byte generic key, compared equal. The control blocks are generated at 
assembly. 

INPUT ACB MACRF=(KEY, 
DIR,IN) 



RETRVE RPL 



ACB=INPUT , 
AREA=IN , 
AREALEN=4 , 
OPTCD=(KEY,DIR, 
SYN,NUP,KEQ,GEN, 
LOC), 

ARG=KEYAREA, 
KEYLEN=5 



You specify all parameters for the 
request in the RPL macro. 



LOOP 



MVC 
GET 



LTR 
BNZ 



KEYAREA, source 
RPL=RETRVE 



15,15 
ERROR 



Search argument for retrieval, moved in 
from a table or a transaction record. 

This GET or identical GETs can be 
issued with no change in the RPL: just 
specify each new search argument in 
the field KEY AREA. 



Process the record. 



ERROR 



LOOP 



Request wasn't accepted or failed. 



IN 



DS 



KEYAREA DS 



CL4 



CL5 



VSAM puts here the address of the 
record within the I/O buffer. 

You specify the search argument here. 



The generic key specifies a class of records. For example, if you search on the 
first third of employee number, VSAM positions at and retrieves the first of 
presumably several records that start with the specified characters. To retrieve 
all of the records in that class, either switch to sequential access or to a 
full-key search with greater-than-or-equal comparison. 
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Example: Addressed-Direct Retrieval 



In this example, a GET macro is used to retrieve fixed-length, 20-byte 
records. The records are to be moved to a work area. 

BLOCK ACB 



DDNAME=INPUT, 

MACRF=(ADR,DIR, 

IN) 



Access-method control block generated 
at assembly. 



GENCB BLK=RPL, 
COPIES=1 , 
ACB=BLOCK, 
OPTCD=(ADR,DIR, 
SYN,NUP,MVE), 
ARG=SRCHADR, 
AREA=IN, 
AREALEN=20 

LTR 15,15 

BNZ CHECKO 

LR 2,1 



Request parameter list generated at 
execution. 



Address of the list. 



LOOP MVC SRCHADR, source 

GET RPL=( 2 ) 

LTR 15,15 

BNZ ERROR 

B LOOP 
CHECKO 
ERROR 

IN DS CL20 

SRCHADR DS CIA 



Search argument for retrieval, 
calculated or moved in from a table or a 
transaction record. 



Process the record. 



Generation failed. 

Request wasn't accepted or failed. 



VSAM puts a record here for each GET 
request. 

You specify the RBA search argument 
here for each request. 



The RBA provided for a search argument must match the RBA of a record. 
Keyed insertion and deletion of records in a key-sequenced data set will 
probably cause the RBAs of some records to change. Therefore, if you 
process a key-sequenced data set by addressed-direct access (or by 
addressed-sequential access using POINT), you need to keep track of 
changes. You can use the JRNAD exit for this purpose. See "EXLST Macro 
(Generate an Exit List)" in the chapter "Control Block Macros." 
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Example: Switch from Direct to Sequential Retrieval 



In this example, GET macros are used to retrieve fixed-length, 100-byte 
records. The control blocks were generated at assembly, but the MODCB 
macro is used to modify the request parameter list to permit switching from 
keyed-direct to keyed-sequential retrieval. For the direct request preceding 
sequential requests, the search argument is an eight-byte, generic key, 
compared equal. Positioning is requested for direct requests. 

INPUT ACB MACRF=(KEY,DIR, Both direct and sequential access 

SEQ , IN ) specified. 



RETRVE RPL 



ACB= INPUT, 

AREA=IN , 

AREALEN=100 f 

OPTCD=(KEY,DIR, 

SYN,NSP,KEQ,GEN, 

MVE), 

ARG=KEYAREA, 

KEYLEN=8 



NSP specifies that VSAM is to 
remember its position. 



LOOP 



LOOP1 



MVC 



KEYAREA, source 



GET 


RPL=RETRVE 


LTR 


15,15 


BNZ 


ERROR 



SEQ 



DIR 



MODCB 


RPL=RETRVE , 




OPTCD=SEQ 


LTR 


15,15 


BNZ 


CHECKO 


B 


LOOP1 


MODCB 


RPL=RETRVE , 




OPTCD=DIR 


LTR 


15,15 


BNZ 


CHECKO 


B 


LOOP 



ERROR 



Search argument for direct retrieval, 
moved in from a table or a transaction 
record. 



Decide whether to switch from one type 
of access to the other. 
If now sequential: 

To remain sequential, branch to 

LOOP1 

To switch to direct, branch to 

DIR 
If now direct: 

To remain direct, branch to 

LOOP 

To switch to sequential, branch to 

SEQ 

Alter request parameter list for 
sequential access. 



No search argument required. 

Alter request parameter list for direct 



Prepare new search argument. 
Request wasn't accepted or failed. 
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CHECKO ... Modification failed. 



IN DS CL100 VSAM puts retrieved records here. 

KEYAREA DS CL8 Specify the generic key for a direct 

request here. 

Positioning is associated with a request parameter list; the MODCB macro is 
used to modify a single request parameter list that alternately defines requests 
for both types of access rather than use a different request parameter list for 
each type. 

With direct retrieval, VSAM doesn't remember its position for subsequent 
sequential retrieval unless you explicitly request it (OPTCD=NSP or UPD). 
After a direct GET for update, VSAM is positioned for a subsequent PUT, 
ERASE, or sequential GET. If you modify OPTCD=(DIR,NUP) to 
OPTCD=SEQ, you must issue POINT to get VSAM positioned for sequential 
retrieval, as NUP indicates that no positioning is desired with a direct GET. 

If you have chained many request parameter lists together, one position is 
remembered for the whole chain. For example, if you issue a GET that gives 
the address of the first request parameter list in the chain, the position of 
VSAM when the GET request is complete is at the record following the 
record defined by the last request parameter list in the chain. Therefore, 
modifying OPTCD=(DIR,NSP) in each request parameter list in a chain to 
OPTCD=SEQ implies continuing with sequential access relative to the last of 
the direct request parameter lists. 



PUT Macro (Store a Record) 

The PUT macro is used to store a record. 
The format of the PUT macro is: 



[label] 


PUT 


RPL= address 



where: 

label 

is one to eight characters that provides a symbolic address for the PUT 
macro. 

RPL= address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: If the PUT macro is being used to load records into an empty data set, 
the STRNO value in the access-method control block must be 1. 



110 OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide 



Example: Keyed-Sequential Insertion 



In this example, a PUT macro is used to perform keyed-sequential insertion. 
Variable-length records with a key length of 15 bytes are to be moved from a 
work area. Some records will be inserted between existing records; other 
records will be added at the end of the data set. 

BLOCK ACB DDNAME=OUTPUT , 
MACRF=(KEY,SEQ, 
OUT) 

LIST RPL ACB=BLOCK, 

AREA=BUILDRCD, 
AREALEN=250, 
OPTCD=(KEY,SEQ, 
SYN , NUP , MVE ) 



Put length of record to be inserted into 
register 2. 

Indicate record length in request 
parameter list. 



LOOP 


L 


2, source 




MODCB 


RPL=LIST, 
RECLEN=( 2 ) 




LTR 


15,15 




BNZ 


CHECKO 




PUT 


RPL=LIST 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


CHECKO 


. . . 




ERROR 






BUILDRCD DS 


CL250 



Modification failed. 

Request wasn't accepted or failed. 



Work area for building records. 



The request parameter list, LIST, is associated with the access-method control 
block, BLOCK. The length of each record to be inserted is put into register 2, 
which is subsequently used by MODCB to change the record length in the 
request parameter list. The record length is, therefore, correctly indicated in 
the request parameter list before the PUT macro is issued. The execution of 
the PUT macro causes VSAM to skip ahead (never back) to the next record. 
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Example: Record RBAs When Loading 

In this example, a PUT macro is used to record the RBAs of records as they 
are loaded into a key-sequenced data set. The RBAs are recorded in a table 
with 20-byte entries (4 bytes for RBA, 15 bytes for associated key, and 1 
byte of padding so the next entry begins on a fullword boundary). 

LA 3 , RBATABLE Address the beginning of the table. 



LOOP 


L 


2, source 


Put length of record to be inserted into 
register 2. 




MODCB 


RPL=LIST, 
RECLEN=( 2 ) 


Indicate record length in request 
parameter list. 




LTR 


15,15 






BNZ 


CHECKO 






PUT 


RPL=LIST 






LTR 


15,15 






BNZ 


ERROR 






SHOWCB 


AREA=(3), 
FIELDS=RBA, 
LENGTH=4 , 
RPL=LIST 


Each SHOWCB puts a record's RBA 
into the table. 




LTR 


15,15 






BNZ 


CHECKO 






MVC 


4( 15,3),keyfield 


Put the record's key field in the table. 




LA 


2,20(3) 


Point to the next entry. 




B 


LOOP 




ERROR 






Request wasn't accepted or failed. 


CHECKO 






Modification or display failed. 



DSECT 



RBATABLE DS 


OF 


RBA DS 


CL4 


KEY DS 


CL15 


DS 


CL1 



Get enough virtual storage for as many 
table entries as there are records in the 
data set. 



Padding to keep each RBA entry on a 
fullword boundary: SHOWCB's display 
area must be on a fullword boundary. 

The need to process a key-sequenced data set by address should be unusual, 
but by recording the RBA of each record in a key-sequenced data set, you 
have search arguments for possible processing of the data set by 
addressed-direct retrieval and by addressed-sequential retrieval using the 
POINT macro. (You don't need to know RBAs to process a key-sequenced 
data set by simple addressed-sequential retrieval, since you go from the 
beginning without any skips.) 

You can display the RBA of a record after you issue a GET or a POINT, as 
well as after you issue a PUT. 
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Example: Skip-Sequential Insertion 



In this example, one PUT macro is used to insert multiple fixed-length, 
100-byte records. Records are to be moved asynchronously from a work area. 

OUTPUT ACB MACRF= ( KEY , SKP , 
OUT) 



GENCB BLK=RPL, 
COPIES=5, 
ACB=OUTPUT , 
AREALEN=100, 
OPTCD=(KEY,SKP, 
ASY , NUP , MVE ) , 
RECLEN=100 

LTR 15,15 

BNZ CHECKO 

Calculate length of each list and use register 
notation with the MODCB macro to complete 
each list. 

MODCB RPL=( 2 ) , 
AREA=( 3 ) , 
NXTRPL=( 4 ) 



LTR 
BNZ 



15,15 
CHECKO 



Generate 5 request parameter lists at 
execution. 



Increase the value in each register and repeat the 
MODCB until all five request parameter lists 
have been completed. The last time, register 4 
must be set to 0. 



LOOP 



PUT 



LTR 
BNZ 



RPL=( 2 ) 



15,15 
NOTACCEP 



Restore address of first list in register 2. 

Build 5 records in WORK. 

Register 2 points to the first request 
parameter list in the chain. The five 
records in WORK are stored with this 
one PUT request. 





CHECK 


RPL=( 2 ) 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


CHECKO 


. . . 




NOTACCEP 


. . . 




ERROR 


• • • 





WORK 



DS 



CL500 



Generation or modification failed. 



Display the feedback field in each 
request parameter list to find out which 
one had an error. 

Contains five 100-byte work areas. 
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You give no search argument for storage: VSAM knows the position of the 
key field in each record and extracts the key from it. Skip sequential insertion 
differs from keyed-direct insertion in the sequence in which records may be 
inserted (ascending nonconsecutive sequence versus random sequence) and in 
performance. 

With skip-sequential insertion, if you insert two or more records into a control 
interval, VSAM doesn't write the contents of the buffer to direct-access 
storage until you have inserted all of the records. With direct insertion, 
VSAM writes the contents of the buffer after you have inserted each record. 



Example: Keyed-Direct Insertion 



In this example, a PUT macro is used to move fixed-length, 100-byte records 
from a work area. 



OUTPUT ACB 



DIRECT RPL 



MACRF=(KEY,DIR, 
OUT) 

ACB=OUTPUT , 

AREA=WORK, 

AREALEN=100, 

OPTCD=(KEY,DIR, 

ASY,NUP,MVE), 

RECLEN=100 



LOOP PUT RPL=DIRECT 
LTR 15,15 
BNZ NOTACCEP 





CHECK 


RPL=DIRECT 






LTR 


15,15 






BNZ 


ERROR 




NOTACCE 


B 
P . . . 


LOOP 


Request wasn't accepted 


ERROR 






Request failed. 



WORK DS CL100 

The macros are described, as follows: 



Work area. 



• ACB specifies that the data set, OUTPUT, into which records are to be 
inserted, is opened for keyed-direct, ouput processing. 

• RPL specifies that the record to be inserted into the OUTPUT data set 
resides in a 100-byte area, WORK. 

VSAM extracts the key from the key field of each record found at WORK. 
Using keyed-direct access is very similar to using skip sequential access. 
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Example: Addressed-Sequential Addition 

In this example, a PUT macro is used to add variable-length records to a data 
set. The data set is assumed to be an entry-sequenced data set because 
records cannot be inserted into or added to a key-sequenced data set with 
addressed access. 

BLOCK ACB MACRF= ( ADR , SEQ , 
OUT) 

LIST RPL ACB=BLOCK, 

AREA=NEWRCD , 
AREALEN=100, 
OPTCD=(ADR,SEQ, 
SYN , MVE ) 



LOOP 





L 


3, source 




MODCB 


RPL=LIST, 
RECLEN=( 3 




LTR 


15,15 




BNZ 


CHECKO 




PUT 


RPL=LIST 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


CHECKO 


. . . 




ERROR 






NEWRCD 


DS 


CL100 



Build the record. 

Put the length of the record into register 
3. 

Indicate length of new record. 



Modification failed. 

Request wasn't accepted or failed. 



Build record in this work area. 



Each record is stored in the next position after the last record in the data set. 
You do not have to specify an RBA or do any explicit positioning (with the 
POINT macro). Addressed addition of records is always identical to loading a 
data set: when additional space is required, VSAM extends the data set. 

The only difference between addressed-sequential and addressed-direct 
addition is when the buffers are written to external storage. The buffer is 
written to external storage only when it is full for sequential addition; it is 
written after each record for direct addition. You cannot use direct storage to 
load records into a data set for the first time; you must use sequential storage. 
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Example: Keyed-Sequential Update 



In this example, GET and PUT macros are used to retrieve and update 
fixed-length, 50-byte records. Records are updated synchronously in a work 
area. This example requires the use of a work area because you cannot update 
a record in the I/O buffer. 

UPDATA ACB 



MACRF=(KEY,SEQ, 
OUT) 



LIST RPL ACB=UPDATA, 
AREA=WORK, 
AREALEN=50, 
OPTCD=(KEY,SEQ, 
SYN,UPD,MVE) 



UPD indicates the record may be stored 
back (or deleted). 



LOOP GET 


RPL=LIST 


LTR 


15,15 


BNZ 


ERROR 


Decide whether to update the record. 


B 


LOOP 


Do update the record. 




PUT 


RPL=LIST 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 


ERROR 





Don't update it; retrieve another. 



Store the record back. 



Request wasn't accepted or failed. 



WORK 



DS 



CL50 



VSAM puts the retrieved record here. 



A GET for update (OPTCD=UPD) must precede a PUT for update. Besides 
retrieving the record to be updated, GET positions VSAM at the record 
retrieved, in anticipation of the succeeding update (or deletion). It is not 
necessary for you to store back (or delete) the record that you retrieved for 
update. VSAM's position at the record previously retrieved allows you to 
issue another GET to retrieve the following record. You cannot then, 
however, store back the previous record: the position for update has been 
forgotten because of the following GET. 
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Example: Keyed-Direct Update 



In this example, GET and PUT macros are used to retrieve and update 
records. The MODCB macro is used to modify record length (RECLEN) in 
the request parameter list when an update causes the record length to change. 
The maximum record length is 120 bytes. The search argument is a full key 
(five bytes), compared equal. 



INPUT ACB MACRF=(KEY,DIR, 
OUT) 

UPDTE RPL ACB=INPUT , 
AREA=IN, 
AREALEN=120, 
OPTCD=(KEY,DIR, 
SYN,UPD,KEQ,FKS, 
MVE), 

ARG=KEYAREA, 
KEYLEN=5 



UPD indicates the record may be stored 
back (or deleted). 



Process input and get search argument into 
KEY AREA; proceed to retrieve a record. 

LOOP GET RPL=UPDTE 

LTR 15,15 

BNZ ERROR 

SHOWCB RPL=UPDTE, 

AREA=RLNGTH , 

FIELDS=RECLEN, 

LENGTH=4 



LTR 
BNZ 



15,15 
CHECKO 



Update the record. Does the update change the 
record's length? 



B 
L 
MODCB 

LTR 
BNZ 
PUT 
LTR 
BNZ 
B 



STORE 

5, length 

RPL=UPDTE , 
RECLEN=( 5 ) 

15,15 

CHECKO 

RPL=UPDTE 

15,15 

ERROR 

LOOP 



STORE 



ERROR 
CHECKO 



IN DS CL120 
KEYAREA DS CL5 
RLNGTH DS F 



Display the length of the record. 



No, length not changed. 

Yes, load new length into register 5. 

Modify length indication in the request 
parameter list. 



Request wasn't accepted or failed. 
Display or modification failed. 



Work area for retrieving, updating, and 
storing a record. 

Search argument for retrieving a 
record. 

Area for displaying the length of a 
retrieved record. 
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You cannot update records in the I/O buffer. A direct GET for update 
positions VSAM at the record retrieved, in anticipation of storing back (or 
deleting) the record. This positioning also allows you to switch to sequential 
access to retrieve the next record. 

You. don't have to store back a record that you retrieve for update, but if you 
don't store it back before another retrieval, it's too late to do so. 



Example: Addressed-Sequential Update 



In this example, GET and PUT macros are used to retrieve and update 
records in an entry-sequenced data set. The records are variable in length, 
maximum 200 bytes. The lengths of the records are not changed by update 
(the length of a record can never be changed by addressed access). 



ENTRY 



ACB 



ADRUPD RPL 



MACRF=(ADR,SEQ, 
OUT) 

ACB=ENTRY , 

AREA=WORK, 

AREALEN=200, 

OPTCD=(ADR,SEQ, 

SYN,UPD,MVE) 



UPD indicates update (or deletion). 



LOOP GET RPL=ADRUPD 
LTR 15,15 
BNZ ERROR 





SHOWC 


B RPL=ADRUPD, 






AREA=RLNGTH, 






FIELDS=RECLEN, 






LENGTH=4 




LTR 


15,15 




BNZ 


CHECKO 
RPL=ADRUPD 




PUT 






LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


ERROR 


. . . 




CHECKO 






WORK 


DS 


CL200 


RLNGTH 


DS 


F 



Find out how long the record is. 



Request wasn't accepted or failed. 
Display failed. 



Record-processing work area. 
Display area for length of records. 

If you have inactive records in your entry-sequenced data set, you may reuse 
the space they occupy by retrieving the records for update and restoring a 
new record in their place. 

With a key-sequenced data set, it is not possible to change the length of 
records by addressed update because the index is not used and VSAM could 
not split a control interval if required because of changing record length. 



118 OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide 



Example: Mark Records Inactive 



Addressed-direct update varies from sequential update in the specification of 
an RBA for a search argument. 



In this example, GET and PUT macros are used to retrieve a record from an 
entry-sequenced data set and to mark it as inactive. The record is marked as 
inactive by putting a hexadecimal 'FF' in first byte of a record. The inactive 
record will not be sequentially retrieved except for update. 

ENTRYSEQ ACB MACRF= ( ADR , DIR , 
OUT) 



LIST RPL ACB=ENTRYSEQ, 
AREA=RECORD , 
AREALEN=100, 
OPTCD=(ADR,DIR, 
SYN , UPD , MVE ) 



UPD indicates update: storing the 
record back marked inactive. 



LOOP 



record. 



B 



GET RPL=LIST 




LTR 15,15 




BNZ ERROR 




ler you still want the data in the 




LOOP 


Yes, retrieve the next record. 


MVI RECORD, X'FF 1 


No, flag the record inactive. 



ERROR 
RECORD 



LTR 
BNZ 
B 

DS 



15,15 
ERROR 
LOOP 

CL100 



Storing the record with an inactive 
indicator is equivalent to deletion for an 
entry-sequenced data set. 



Request wasn't accepted or failed. 
Work area for marking records. 



Records of an entry-sequenced data set can't be deleted. If a record loses its 
usefulness for your application, your program can mark it inactive by placing 
a unique flag in some conventional part of the record so that when your 
programs retrieve the record thereafter they can recognize and bypass it. You 
can use the space occupied by an inactive record by retrieving it for update 
and storing a new record in its place. 



ERASE Macro (Delete a Record) 



The ERASE macro is used with the GET macro to delete records in a 
key-sequenced or relative record data set. 

The format of the ERASE macro is: 



[label] 


ERASE 


RPL= address 



where: 
label 



is one to eight characters that provides a symbolic address for the ERASE 
macro. 
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Example: Keyed-Direct Deletion 



RPL« address 

specifies the address of a request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 



In this example, GET and ERASE macros are used to retrieve and delete 
records. Not every record retrieved for deletion is deleted. The search 
argument is a full key (5 bytes), compared equal. 



DELETE ACB 



LIST 



RPL 



MACRF=(KEY,DIR, 
OUT) 

ACB=DELETE , 

AREA=WORK / 

AREALEN=50, 

ARG=KEYFIELD, 

OPTCD=(KEY,DIR, 

SYN,UPD,MVE,FKS, 

KEQ) 



UPD indicates deletion. 



LOOP 



MVC 



KEYFIELD, source 



Search argument for retrieval, from a 
table or transaction record. 





GET 


RPL=LIST 






LTR 


15,15 






BNZ 


ERROR 




Decide whether to delete the record. 






B 


LOOP 


No, retrieve the next record. 




ERASE 


RPL=LIST 


Yes, delete the record. 




LTR 


15,15 






BNZ 


ERROR 






B 


LOOP 




ERROR 






Request wasn't accepted or failed 


WORK 


DS 


CL50 


Examine the data record here. 


KEYFIELD DS 


CL5 


Search argument. 



When you retrieve a record for deletion (OPTCD=UPD, same as retrieval for 
update), VSAM is positioned at the record retrieved, in anticipation of a 
succeeding ERASE (or PUT) request for that record. You are not required to 
issue such a request, though. Another GET request nullifies any previous 
positioning for deletion or update. 

Keyed-sequential retrieval for deletion varies from direct in not using a search 
argument (except for possible use of the POINT macro). Skip-sequential 
retrieval for deletion (OPTCD=(SKP,UPD)) has the same effect as direct, 
but it is faster or slower depending on the number of control intervals 
separating the records being retrieved. 
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Example: Addressed-Sequential Deletion 



In this example, the ERASE macro is used to delete records from a 
key-sequenced data set. Not every record retrieved for deletion is deleted. 
Skipping is effected by POINT macro. 

DELETE ACB MACRF= ( ADR , SEQ , 
OUT) 



REQUEST RPL 



ACB=DELETE , 

AREA=WORK, 

AREALEN=100, 

ARG=ADDR, 

OPTCD=(ADR,SEQ, 

ASY,UPD,MVE) 



UPD indicates deletion. 



LOOP 



B 
MVC 



RETRIEVE 
ADDR, source 



POINT RPL=REQUEST 

CHECK RPL=REQUEST 

LTR 15,15 

BNZ ERROR 

RETRIEVE GET RPL=REQUEST 

CHECK RPL=REQUEST 

LTR 15,15 

BNZ ERROR 

Decide whether to delete the record. 

B LOOP 

ERASE RPL=REQUEST 

CHECK RPL=REQUEST 

LTR 15,15 

BNZ ERROR 

B LOOP 

ERROR 



Decide whether you need to skip to 
another position (forward or 
backward). 

No, bypass the POINT. 

Yes, move search argument for POINT 
into search-argument field. 

Position VSAM to the record to be 
retrieved next. 



No, skip ERASE and CHECK. 
Yes, delete the record. 



Request wasn't accepted or failed. 



ADDR 
WORK 



DS 
DS 



F 
CL100 



RBA search argument for POINT. 
Work area. 



Addressed deletion is allowed only for a key-sequenced data set. The records 
of an entry-sequenced data set are fixed. When records are deleted using 
addressed deletion from a key-sequenced data set, the index is not updated. 
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POINT Macro (Position for Access) 



Example: Position with POINT 



The POINT macro is used to position for access. 
The format of the POINT macro is: 



[label] 


POINT 


RPL= address 



where: 

label 

is one to eight characters that provides a symbolic address for the POINT 
macro. 

RPL~ address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 



In this example, the POINT macro is used to position at a record identified by 
a full key (five-byte) search argument, compared equal. 



BLOCK 



ACB 



POSITION RPL 



DDNAME=IO 

ACB=BLOCK, 

AREA=WORK, 

AREALEN=50, 

ARG=SRCHKEY , 

OPTCD=(KEY,SEQ, 

SYN,KEQ,FKS) 



Default MACRF options sufficient. 

ARG operand and KEQ and FKS 
OPTCD options define the POINT 
request. 



LOOP 



MVC 



LOOP1 



SRCHKEY, source 



Search argument for positioning, 
moved in from a table or a transaction 
record. 



ERROR 



POINT 


RPL=POSITION 




LTR 




15,15 




BNZ 




ERROR 




GET 




RPL=POSITION 




LTR 




15,15 




BNZ 




ERROR 




jcord. Decide whether to skip to 
ion (forward or backward). 




B 




LOOP 


Yes, skip. 


B 




LOOP1 


No, continue in consecutive sequence 
Request wasn't accepted or failed. 



SRCHKEY DS CL5 
WORK DS CL50 



Search-argument field for POINT 
request. 

VSAM puts a record here for each GET 
request. 
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No access is gained to a record with POINT. POINT causes VSAM to be 
positioned ahead or back to the specified record for a subsequent sequential 
GET request, which retrieves the record. If, after positioning, you issue a 
direct request by way of the same request parameter list, VSAM doesn't 
remember the position established by the POINT. VSAM would then either 
be positioned somewhere else or not positioned at all, depending on whether 
OPTCD=NSP or UPD was specified or OPTCD=NUP. 

Positioning by address is identical to positioning by key, except that the 
search argument is an RBA, which must be matched equal to the RBA of a 
record in the data set. 

When a POINT is issued for a subsequent VSAM request, both the POINT 
and the request must be in the same processing mode. 



CHECK Macro (Suspend Processing) 



The CHECK macro is used to suspend processing to await the completion of 
VSAM's processing of the request. 

The format of the CHECK macro is: 



[label] 


CHECK 


RPL= address 



where: 

label 

is one to eight characters that provides a symbolic address for the CHECK 
macro. 

RPL= address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 
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Example: Check Return Codes after an Asynchronous Request 

In this example, return codes are checked after an asynchronous request. The 
CHECK macro is used to cause an exit to be taken if there is a logical or 
physical error or if the end of the data set is reached. 

REQPARMS RPL OPTCD=ASY 

RPL=REQPARMS 



GET 

LTR 15,15 



BNZ 



REJECTED 



CHECK RPL=REQPARMS 



LTR 15,15 
BNZ FAILURE 



Was the request completed 
successfully? 

Zero indicates the request was 
accepted. If it wasn't accepted, register 
15 contains 4: REQPARMS is active for 
another request. 

Continue to work on something that is 
not dependent on the request. 

CHECK would cause one of the three 
exits to be taken if there was a logical or 
physical error or if the end of the data 
set was reached and an active exit list 
exists. 

Test return indication in register 15. 

Zero indicates the request completed 
successfully. If it failed, register 1 5 
contains 8 or 12: there was a logical or a 
physical error. 



REJECTED 
FAILURE 

Always test register 15 after the CHECK unless you provide exit routines 
that terminate processing. If a routine returns to VSAM, register 15 is reset 
and control is passed back to your program immediately after the CHECK. 
An error-analysis routine normally issues SHOWCB or TESTCB to examine 
the feedback field in the request parameter list, so that when your processing 
program gets control back, it doesn't have to analyze the error — but it may 
alter its processing if there was an error. If you don't provide an error-analysis 
routine, your program can issue SHOWCB or TESTCB to analyze an error 
when it gets control back following the CHECK. 



Example: Check Return Codes after a Synchronous Request 



With synchronous processing, you should test register 15 after the request 
because the request may not have been accepted (register 15 contains 4) or 
because an error might have occurred (8 or 12): 



GET RPL=REQPARMS 

LTR 15,15 



BNZ 



REJFAIL 



Was the request completed 
successfully? 

If branch isn't taken, request was 
accepted and completed successfully. 



REJFAIL 
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Example: Overlap Processing 



In this example, the CHECK macro is used to await completion of a request 
before continuing to other processing. Access is asynchronous. 



BLOCK 

LIST 



ACB 
RPL 



ACB=BLOCK, 
AREA=WORK, 
AREALEN=50, 
OPTCD=ASY 



Asynchronous access. 



LOOP GET RPL=LIST 

LTR 15,15 

BNZ NOTACCEP 

Do other processing. 

CHECK RPL=LIST 



WORK 



DS 



CL50 



Suspends your processing to await 
completion of GET if necessary and to 
cause VSAM to indicate return codes. 



LTR 


15,15 




BNZ 


ERROR 




Process the record. 






B 


LOOP 




NOTACCEP . . . 




Request wasn't accepted. 


ERROR 




Request failed. 



Work area. 



After issuing the request, make sure that VSAM accepted it before you go on 
to do other processing. When you have done as much other processing as you 
can, issue the CHECK macro. VSAM will not give you back control now 
until the request is complete. If you don't want to issue CHECK until you 
know the request is complete, use the ECB operand of the RPL macro or the 
IO=COMPLETE operand of the TESTCB macro. After you issue the 
CHECK, VSAM immediately returns a code and takes an exit, if necessary. 
See "RPL Macro (Generate a Request Parameter List)" and "GENCB Macro 
(Generate a Request Parameter List)" in the chapter "Control Block 
Macros" for information on the ECB operand. 
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Example: Suspend a Request for Many Records 



In this example, a CHECK macro is issued for the first request parameter list 
in a chain of parameter lists. If an error occurred for one of the request 
parameter lists in the chain and you have supplied error-analysis routines, 
VSAM takes a LERAD or SYNAD exit before it returns control to your 
program after the CHECK. 

FIRST RPL ACB=BLOCK, 
AREA=AREA1 , 
AREALEN=50, 
NXTRPL=SECOND, 
OPTCD=ASY 

SECOND RPL ACB=BLOCK, 
AREA=AREA2 , 
AREALEN=50 , 
NXTRPL=THIRD, 
OPTCD=ASY 

THIRD RPL ACB=BLOCK / 
AREA=AREA3 , 
AREALEN=50 , 
OPTCD=ASY 



Last list doesn't indicate a next list. 



LOOP GET 


RPL=FIRST 


LTR 


15,15 


BNZ 


NOTACCEP 


Do other processing. 




CHECK 


RPL=FIRST 


LTR 


15,15 


BNZ 


ERROR 



Request gives the address of the first 
request parameter list. 



Process the three records retrieved by the GET. 

B LOOP 

NOTACCEP . . . 
ERROR 



AREA1 DS CL50 



Request wasn't accepted. 

Display the feedback field 
(FIELDS-FDBK) of each request 
parameter list to find out which one had 
an error. 

A single GET request causes VSAM to 
put a record in each of AREA1, 
AREA2, and AREA3. 



AREA2 DS 
AREA3 DS 



CL50 
CL50 



After the CHECK, register 15 is set to indicate the status of the request. A 
code of indicates that no error was associated with any of the request 
parameter lists. Any other code indicates that an error occurred for one of the 
request parameter lists. You should issue a SHOWCB macro for each request 
parameter list in the chain to find out which one had an error. VSAM doesn't 
process any of the request parameter lists beyond the one with an error. 
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ENDREQ Macro (Terminate a Request) 



The ENDREQ macro is used to terminate a request. 
The format of the ENDREQ macro is: 



[label] 


ENDREQ 


RPL= address 



where: 

label 

is one to eight characters that provides a symbolic address for the 
ENDREQ macro. 

RPL= address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 



Example: Release Positioning for Another Request 



In this example, the ENDREQ macro is used to cause VSAM to release 
positioning for a request parameter list. There are three request parameter 
lists, all of which require VSAM to have the ability to remember its position, 
one only temporarily and two until VSAM is explicitly requested to forget its 
position. VSAM is given the ability to remember only two positions 
concurrently (STRNO=2). 



BLOCK 



ACB 



SEQ RPL 
DIRUPD RPL 

DIRNUP RPL 



MACRF=(SEQ,DIR), 
STRNO=2 

ACB=BLOCK, 
OPTCD=SEQ 

ACB=BLOCK, 
OPTCD=(DIR,UPD) 

ACB=BLOCK, 
OPTCD=(DIR,NUP) 



VSAM must remember its position. 

VSAM must remember its position until 
explicitly requested to forget it by PUT 
or ENDREQ. 

VSAM must be able to temporarily 
remember its position. 



LOOP 



GET 


RPL=SEQ 


LTR 


15,15 


BNZ 


ERROR 


GET 


RPL=DIRNUP 


LTR 


15,15 


BNZ 


ERROR 


GET 


RPL=DIRUPD 


LTR 


15,15 


BNZ 


ERROR 



VSAM now remembers its position for 
this request. 



VSAM remembers its position for this 
request only while it is processing the 
request. 



VSAM can therefore remember its 
position for this request, even though 
STRNO-2. 
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Decide whether to update the record. 



B 


FORGET 


PUT 


RPL=DIRUPD 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 


FORGET ENDREQ 


RPL=DIRUPD 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 



No. 

Yes, update the record, causing VSAM 
to forget its position for DIRUPD. 



Cause VSAM to forget its position for 
DIRUPD. 



ERROR . . . Request wasn't accepted or failed. 

The use of ENDREQ illustrated here is to cause VSAM to forget its position 
for one request parameter list so a request defined by another request 
parameter list can be issued. When PUT is issued after a DIRUPD GET 
request, ENDREQ need not be issued, since PUT causes VSAM to forget its 
position (the next DIRUPD GET doesn't depend on VSAM's remembering 
its position). You need to cause VSAM to forget its position when you have 
issued requests for as many request parameter lists requiring concurrent 
positioning as the number you specified for STRNO (in the ACB macro) and 
you want to issue a request for yet another request parameter list. In the 
example, DJRNUP cannot be reissued unless VSAM is freed from 
remembering its position for either SEQ or DIRUPD. VSAM remembers its 
position for SEQ because SEQ's requests are sequential and depend on 
VSAM's remembering its position. Another result of ENDREQ is that buffers 
are written out if required. 

To cause VSAM to give up its position associated with a chain of request 
parameter lists, specify the first request parameter list in the chain in your 
ENDREQ macro. 

ENDREQ can also be used to cancel an asynchronous request — rather than 
suspending processing with CHECK. But simply ignoring a request whose 
completion you are not interested in is adequate. 

Because VSAM remembers its position after a direct GET with 
OPTCD-UPD, if no PUT or ENDREQ follows, you can switch to sequential 
access and use the positioning for a GET. 
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USING ISAM PROGRAMMING WITH VSAM 



VSAM, through its ISAM interface program, enables a debugged program 
that processes an indexed-sequential data set to process a key-sequenced data 
set. The key-sequenced data set may have been converted from an 
indexed-sequential or a sequential data set (or another VSAM data set) or 
may have been loaded by one of your own programs. The loading program 
may be coded with VSAM macros or with ISAM macros or PL/I or COBOL 
statements. That is, you can load records into a newly defined key-sequenced 
data set with a program that was coded to load records into an 
indexed-sequential data set. 

There are some minor restrictions on the types of processing an ISAM 
program may do if it is to be able to process a key-sequenced data set. These 
restrictions are described in "Restrictions in the Use of the ISAM Interface" 
later in this chapter. 

Significant performance improvement can be gained by modifying an ISAM 
program that issues multiple OPEN and CLOSE macros to switch between a 
QISAM and BISAM DCB. The ISAM program can be modified to open the 
QISAM and BISAM DCBs at the beginning of the program and to close them 
when all processing is complete. The performance improvement is 
proportional to the frequency of OPEN and CLOSE macros in the ISAM 
program. 

Figure 13 shows the relationship between ISAM programs processing VSAM 
data with the ISAM interface and VSAM programs processing the data. 



Indexed 
Sequential 
Data Sets 



New Data Sets 



Existing ISAM Programs 




ISAM 
Interface 



Access 

M W 



Unmodified 



Interpret 




Key-Sequenced 
Data Sets 
with Indexes 



z: 



Each Request 



Modified to 
Meet Restrictions 



Access 



VSAM 



Access 



ISAM Programs 
Converted to 
VSAM Programs 




(To take advantage of additional 
functions of VSAM) 



Figure 13. Use of ISAM Processing Programs 
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How an ISAM Program Can Process a VSAM Data Set 



When a processing program that uses ISAM (assembler-language macros, 
PL/I or COBOL) issues an OPEN to open a key-sequenced data set, the 
ISAM interface is given control to: 

• Construct control blocks that are required by VSAM. 

• Load the appropriate ISAM interface routines into virtual storage. 

• Initialize the ISAM DCB (data control block) to enable the interface to 
intercept ISAM requests. 

• Take the DCB exit requested by the processing program. 

The ISAM interface intercepts each subsequent ISAM request, analyzes it to 
determine the equivalent keyed VSAM request, defines the keyed VSAM 
request in a request parameter list, and initiates the request. 

The ISAM interface receives return codes and exception codes for logical and 
physical errors from VSAM, translates them to ISAM codes, and routes them 
to the processing program or error-analysis (SYNAD) routine by way of the 
ISAM DCB or DECB. Figure 14 shows QISAM error conditions and the 
meaning they have when the ISAM interface is being used. 

Figure 15 shows BISAM error conditions and the meaning they have when 
the ISAM interface is being used. 

If invalid requests occur in BISAM that didn't occur previously and the 
request parameter list indicates that VSAM isn't able to handle concurrent 
data-set positioning, the value specified for the STRNO AMP parameter 
should be increased. If the request parameter list indicates an exclusive-use 
conflict, reevaluate the share options associated with the data. 

Figure 16 gives the contents of registers and 1 when a SYNAD routine 
specified in a DCB gets control. 

You may also specify a SYNAD routine by way of the DD AMP parameter 
(see "JCL for Processing with the ISAM Interface" later in this chapter). 
Figure 17 gives the contents of registers and 1 when a SYNAD routine 
specified by way of AMP gets control. 
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Byte and Offset 


QISAM Meaning 


Error Detected By 


Request Parameter 
list Error Code 


DCBEXCD1 








BitO 


Record not found 


Interface 








VSAM 


16 






VSAM 


24 


Bitl 


Invalid device address 






Bit 2 


Space not found 


VSAM 


28 






VSAM 


40 


Bit 3 


Invalid request 


Interface 
Interface 
Interface 








VSAM 


4 






VSAM 


20 






VSAM 


36 






VSAM 


64 






VSAM 


96 


Bit 4 


Uncorrectable input 
error 


VSAM 


4 






VSAM 


8 






VSAM 


12 


Bit 5 


Uncorrectable output 
error 


VSAM 


16 






VSAM 


20 






VSAM 


24 


Bit 6 


Unreachable block 
(input) 


VSAM 




Bit 7 


Unreachable block 
(output) 


VSAM 




DEBEXCD2 








BitO 


Sequence check 


VSAM 
Interface 


12 


Bitl 


Duplicate record 


VSAM 


8 


Bit 2 


DCB closed when error VSAM 
routine entered 





Bit 3 Overflow record Interface 

Figure 14 (Part 1 of 2). QISAM Error Conditions 



Interface/VSAM Meaning 



Record not found (SETL K for a deleted 
record) 

Record not found 

Record on non-mountable volume 

Always zero 

Data set cannot be extended 

Virtual storage not available 

Two consecutive SETL requests 

Invalid SETL (I or ID) 

Invalid generic key (KEY=0) 

Request after end-of-data 

Exclusive use conflict 

No key range defined for insertion 

Placeholder not available for concurrent 
data-set positioning 

Key change attempted 

Physical read error (register 15 contains 
a value of 12) in the data component 

Physical read error (register 15 contains 
a value of 12) in the index component 

Physical read error (register 15 contains 
a value of 12) in the sequence set of the 
index 

Physical write error (register 15 contains 
a value of 12) in the data component 

Physical write error (register 15 contains 
a value of 12) in the index component 

Physical write error (register 15 contains 
a value of 12) in the sequence set of the 
index 

Logical error not covered by other 
exception codes 

Logical error not covered by other 
exception codes 



Sequence check 

Sequence check (occurs only during 
resume load) 

Duplicate record 

Error in Close 



Always one 
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Byte and Offset QISAM Meaning Error Detected By 

Bit 4 Length of logical Interface 

record is greater than 
DCBLRECL (VLR 
only) 

VSAM 

Bits 5-7 Reserved 

Figure 14 (Part 2 of 2). QISAM Error Conditions 



Request Parameter 
list Error Code 



108 



Interface/VSAM Meaning 

Length of Logical record is greater than 
DCBLRECL (VLR only) 



Invalid record length 
Always zero 









Request Parameter 


Byte and Off set 


BISAM Meaning 


Error Detected By 


List Error Code 


DECBEXC1 








BitO 


Record not found 


VSAM 


16 






VSAM 


24 


Bit 1 


Record length check 


VSAM 


108 


Bit2 


Space not found 


VSAM 


28 


Bit 3 


Invalid request 


Interface 








VSAM 


20 






VSAM 


36 






VSAM 


64 






VSAM 


96 


Bit 4 


Uncorrectable I/O 
error 


VSAM 




Bit 5 


Unreachable block 


VSAM 




Bit 6 


Overflow record 


Interface 




Bit 7 


Duplicate record 


VSAM 


8 


DECBEXC2 








Bits - 5 


Reserved 






Bit 6 


Channel program 
initiated by an 
asynchronous routine 






Bit 7 


Previous macro was 
READKU 


Interface 





Figure 15. BISAM Error Conditions 



Interface/VSAM Meaning 

Record not found 

Record on non-mountable volume 

Record length check 

Data set cannot be extended 

No request parameter list available 

Exclusive-use conflict 

No key range defined for insertion 

Placeholder not available for concurrent 
data-set positioning 

Key change attempted 

Physical error (register 15 will contain a 
value of 12) 

Logical error not covered by any other 
exception code 

Always one for READ requests 

Duplicate record 

Always zero 
Always zero 

Previous macro was READ KU 



Reg. BISAM 

Address of the DECB 



QISAM 

0, or, for a sequence check, the address of a field 
containing the higher key involved in the check 



1 Address of the DECB 

Figure 16. Register Contents for DCB-Specified ISAM SYNAD Routine 
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Reg. BISAM 

Address of the DECB 



QISAM 

0, or, for a sequence check, the address of a field 
containing the higher key involved in the check 



1 Address of the DCB Address of the DCB 

Figure 17. Register Contents for AMP-Specified ISAM SYNAD Routine 

If your SYNAD routine issues the SYNAD AF macro, registers and 1 are 
used to communicate. When you issue SYNADAF, register must have the 
same contents it had when the SYNAD routine got control and register 1 
must contain the address of the DCB. 

When you get control back from SYNADAF, the registers have the same 
contents they would have if your program were processing an 
indexed-sequential data set: register contains a completion code and register 
1 contains the address of the SYNADAF message. 

The completion codes and the format of a SYNADAF message are given in 
OS/VS Data Management Macro Instructions. 

Figure 18 shows abnormal-end (ABEND) codes issued by the ISAM interface 
when there is no other method of communicating the error to the user. 

If a SYNAD routine specified by way of AMP issues the SYNADAF macro, 
the operand ACSMETH may specify either QISAM or BISAM, regardless of 
which of the two is used by your processing program. 

A dummy DEB is built by the ISAM interface to support: 

• References by the ISAM processing program 

• Checkpoint/restart 

• Abnormal end 



ABEND Code Error Detected By Module/Routine 

03B OPEN OPEN/VALID CHECK 



031 



ABEND 
Issued By 

OPEN 



039 



001 



VSAM 


SYNAD 


SYNAD 


VSAM 


SCAN/GET and SETL 


SYNAD 


LOAD 


LOAD/RESUME 


LOAD 


LOAD 


LOAD 


LOAD 


VSAM 


SCAN/EODAD 


SCAN 


VSAM 


SYNAD 




BISAM 


SYNAD 


BISAM 


BISAM 


BISAM 


BISAM 



Error Condition 

Validity check; either (1) Access Method Services 
and DCB values for LRECL, KEYLE, and RKP 
do not correspond, or (2) DISP=OLD, the DCB 
was opened for output, and the number of logical 
records is greater than zero (RELOAD is implied) 

SYNAD (ISAM) was not specified and a VSAM 
physical and logical error occurred 

SYNAD (ISAM was not specified and an invalid 
request was found 

SYNAD (ISAM) was not specified and a sequence 
check occurred 

SYNAD (ISAM) was not specified and the RDW 
(Record Descriptor Word) was greater than 
LRECL 

End-of-data was found, but there was no EODAD 
exit 

I/O error detected 

I/O error detected during check 

Invalid request 



Figure 18. ABEND Codes Issued by the ISAM Interface 
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Figure 19 shows the DEB fields that are supported by the ISAM interface; 
field meanings are the same as in ISAM, except as noted. 

DED Section Bytes Fields Supported 

PREFIX 16 LNGTH 

BASIC 32 TCBAD, OPATB, DEBAD, OFLGS (DISP ONLY), 

FLGS1 (ISAM-interface bit), AMLNG (104), NMEXT(2), 
PRIOR, PROTG, DEBID, DCBAD, EXSCL (0-DUMMY 
DEB), APPAD 

ISAM DEVICE 16 EXPTR, FPEAD 

DIRECT ACCESS 16 UCBAD (VSAM UCB) 

ACCESS METHOD 24 WKPT5 (ISAM-interface control block pointer), FREED 

(pointer to IDAIIFBF) 

Figure 19. DEB Fields Supported by ISAM Interface 



Converting an Indexed-Sequential Data Set 



Access Method Services is used to convert an indexed-sequential data set to a 
key-sequenced data set. Assuming that a master and/or user catalog has been 
defined, define a key-sequenced data set with the attributes, performance 
options, etc., that you want and then you use the Access Method Services 
REPRO command to convert the indexed-sequential records and load them 
into the key-sequenced data set. See the appropriate Access Method Services 
publication for information about defining a key-sequenced data set and 
about converting an indexed-sequential data set. VSAM builds the index for 
the key-sequenced data set as it loads the data set. 

Each volume of a multivolume component must be on the same type of 
device; the data component and the index component, however, may be on 
volumes of devices of different types. 

When you define the key-sequenced data set into which the 
indexed-sequential data set is to be copied, you must specify the attributes of 
the VSAM data set for variable- and fixed-length records. For variable-length 
records: 

• VSAM record length equals ISAM DCBLRECL-4 
. VSAM key length equals ISAM DCBKEYLE 

• VSAM key position equals ISAM DCBRKP-4 
For fixed-length records: 

• VSAM record length (average and maximum must be the same) equals 
ISAM DCBLRECL (+ DCBKEYLE, if ISAM DCBRKP equals and 
records are unblocked) 

. VSAM key length equals ISAM DCBKEYLE 

• VSAM key position equals ISAM DCBRKP 

Care should also be taken with the level of sharing allowed when the 
key-sequenced data set is defined. If the ISAM program opens multiple DCBs 
pointing to different DD statements, a share-options value of 1, which is the 
default, allows only the first DD statement to be opened. See the appropriate 
Access Method Services publication for a description of the share-options 
values. 



134 OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide 



JCL for Converting from ISAM to VSAM 



In VS1 and VS2 systems, JCL is used to identify data sets and volumes for 
allocation. In a VS2 system, data sets can also be allocated dynamically. See 
OS/VS2 JCL and OS/VS2 System Programming Library: TSO for a 
description of dynamic allocation. 

If JCL is used to describe an indexed-sequential data set to be converted to 
VSAM using the Access Method Services REPRO command, include 
DCB=DSORG=IS. The key-sequenced data set that is to receive the 
converted data set need not be described in JCL if it is to reside in a 
previously defined data space. If it is to reside alone in a data space, the data 
set is either allocated dynamically by name (in which case the volume on 
which it is to reside must be mounted) in a VS2 system or is defined in a DD 
statement in VS1 or VS2 that includes DISP=OLD, volume and unit 
information, the AMP parameter, and DSNAME=dsname, where dsname is 
the name of the key-sequenced data set. In a VS1 or VS2 system, use a 
STEPCAT or JOBCAT DD statement as described in the chapter "Opening 
and Closing a Data Set" to make user catalogs available; in a VS2 system, 
you may also use dynamic allocation. 

With ISAM, deleted records are flagged as deleted, but are not actually 
removed from the data set. If your program depends upon a record's only 
being flagged and not actually removed, you may want to keep these flagged 
records when you convert and continue to have your programs process these 
records. The Access Method Services REPRO command has a parameter 
(ENVIRONMENT) that causes VSAM to keep the flagged records when you 
convert. 



JCL for Processing with the ISAM Interface 



To execute your ISAM processing program to process a key-sequenced data 
set, replace the ISAM DD card with a VSAM DD card using the DDNAME 
that was used for ISAM. The VSAM DD card names key-sequenced data set 
and gives any necessary VSAM parameters (by way of AMP). Specify 
DISP=MOD for resume loading and DISP=OLD for all other processing. 
You don't have to specify anything about the ISAM interface itself. The 
interface is automatically brought into action when your processing program 
opens a DCB whose associated DD statement describes a key-sequenced data 
set (instead of an indexed-sequential data set). If you have defined your 
VSAM data set in a user catalog, specify the user catalog in a JOBCAT or 
STEPCAT DD statement. 

The DCB parameter in the DD statement that identifies a VSAM data set is 
invalid. Certain DCB-type information may be specified in the AMP 
parameter, which is described later in this chapter. 

Figure 20 shows the DCB fields supported by the ISAM Interface. 
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Field 

Name Meantag 

BFALN Same as in ISAM; defaults to a doubleword 

BLKSI Set equal to LRECL if not specified 

BUFCB Same as in ISAM 

BUFL The greater value of AMDLRECL or DCBLRECL if not specified 

BUFNO For QISAM, one; for BISAM, the value of STRNO if not specified 

DDNAM Same as in ISAM 

DEBAD During the DCB exit, contains the address of the OPEN work area; after 

the DCB exit, contains the address of the dummy DEB built by the ISAM 
interface 

DEVT Set from the VSAM UCB TYPE 

DSORG Same as in ISAM 

EODAD Same as in ISAM 

ESETL Address of the ISAM interface ESETL routine 

EXCD 1 See the QISAM exception codes 

EXCD2 See the QISAM exception codes 

EXLST Same as in ISAM 

FREED Address of the ISAM-interface dynamic buffering routine (IDAIIFBF) 

GET/PUT For QISAM LOAD, the address of the ISAM-interface PUT routine; for 

QISAM SCAN, 0, the address of the ISAM-interface GET routine, 4, the 
address of the ISAM-interface PUTX routine, and 8, the address of the 
ISAM-interface RELSE routine 

KEYLE Same as in ISAM 

LRAN Address of the ISAM-interface READ K/WRITE K routine 

LRECL Set to the maximum record size specified in the Access Method Services 

DEFINE command if not specified (adjusted for variable-length, fixed, 
unblocked, and RKP=0 records) 

LWKN Address of the ISAM-interface WRITE KN routine 

MACRF Same as in ISAM 

NCP For BISAM, defaults to one 

NCRHI Set to a value of 8 before DCB exit 

OFLGS Same as in ISAM 

OPTCD Bit (W), same as in ISAM; bit 3 (I), dummy records are not to be 

written in the VSAM data set; bit 6 (L), dummy records are to be treated 
as in ISAM; all other options ignored 

RECFM Same as in ISAM; default to unblocked, variable-length records 

RKP Same as in ISAM 

RORG 1 Set to a value of after DCB exit 

RORG2 Set to a value of X'7FFFF' after DCB exit 

RORG3 Set to a value of after DCB exit 

SETL For BISAM, address of the ISAM-interface CHECK routine; for QISAM, 

address of the ISAM-interface SETL routine 



Bit 1 (key-sequence check), same as in ISAM; bit 2 (loading has 
completed), same as in ISAM 



ST 

Figure 20 (Part 1 of 2). DCB Fields Supported by ISAM Interface 
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Field 
Name 

SYNAD 

TIOT 

WKPT1 

WKPT5 
WKPT6 



Meaning 

Same as in ISAM 

Same as in ISAM 

For QISAM SCAN, +112=address of the W1CBF field pointing to the 
current buffer 

Address of the ISAM-interface control block (IICB) 

For QISAM LOAD, address of the dummy DCB work area vector 
pointers; the only field supported is ISLVPTRS+4=pointer to KEYSAVE 



Figure 20 (Part 2 of 2). DCB Fields Supported by ISAM Interface 



AMP Parameter Specification 



When an ISAM processing program is run with the ISAM interface, the AMP 
parameter enables you to specify: 

• The need for extra index buffers for simulating the residency of the highest 
level(s) of an index in virtual storage (BUFNI) 

• Whether to remove records flagged (OPTCD) 

• What record format (RECFM) is used by the processing program 

• The number of concurrent BISAM and QISAM (basic and queued 
indexed-sequential access methods) requests that the processing program 
may issue (STRNO) 

• The name of an ISAM exit routine to analyze physical and logical errors 
(SYNAD) 

The AMP parameter has some subparameters that are peculiar to the ISAM 
interface. The other subparameters of AMP (AMORG, BUFND, BUFSP, 
CROPS, and TRACE), which can also be used with the interface, are 
described in "How to Code JCL" in the chapter "Opening and Closing a 
Data Set." The format of the AMP parameter (with the subparameters 
discussed here) is: 



//... 


DD 


...[AMP= < AMORG , [, 4 BUFNI= number'} 
[,<OFTCD-{I|L|IL}'] 
[,'RECFM={F | FB | V | VB}»] 
[,'STRNO= number'} 
[, t SYNAD=modulename ']] 



where: 

AMORG 

specifies that a VSAM data set is to be processed. 

BVFNl=number 

specifies the number of I/O buffers VSAM is to use for index records. If 
you don't specify BUFNI, VSAM uses as many index buffers as the 
number specified for STRNO (1 if you don't specify STRNO). You may 
specify for BUFNI a number 1 greater than STRNO (2 if you don't specify 
STRNO) to simulate having the highest level of an ISAM index resident. If 
you specify for BUFNI a number 2 or more greater than STRNO, you 
simulate having intermediate levels of the index resident. 
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OPTCD={I|L|IL} 

specifies how records flagged for deletion are to be treated. The values that 
can be specified are: 

L 

specifies that a record marked for deletion by your processing program 
is to be kept in the data set. Although this parameter has the same 
meaning and restrictions for the ISAM interface as it has for ISAM, it 
may have to be specified in the AMP parameter when it wasn't 
previously needed in the ISAM job control language, It is required when 
OPTCD=L is not specified in the DCB in the processing program 
because OPTCD is not merged into the DSCB when the ISAM interface 
is used. 

I 

specifies, when coded along with OPTCD=L in the DCB, that records 
marked for deletion by your processing program are not written into the 
data set by the ISAM interface. If OPTCD=I is specified in the AMP 
parameter, but OPTCD=L isn't specified in the processing program's 
DCB, records flagged for deletion are treated like any other records: 
that is, AMP='OPTCDs=r, without L anywhere specified, has no 
effect. 

EL 

specifies that if your processing program writes a record marked for 
deletion, the ISAM interface is not to put the record into the data set. 
(It issues a VSAM ERASE to delete the old record if your processing 
program had previously read the record for update.) The result of this 
parameter is the same as when AMP = 'OPTCD =F is coded along with 
OPTCD =L in the DCB in the processing program. 

RECFM={F|FB|V|VB} 

specifies the ISAM record format that your processing program is coded 
for. Although this parameter thas the same meaning and restrictions for the 
ISAM interface as it has for ISAM, it may have to be specified in the AMP 
parameter when it wasn't previously required in the ISAM job control 
language. RECFM is required when it is not specified in the DCB in the 
processing program because RECFM is not merged into the DSCB when 
the ISAM interface is used. All VSAM requests are for unblocked records. 
If your program issues a request for blocked records, the ISAM interface 
sets the overflow-record indicator for each record to indicate that each is 
being passed to your program unblocked. If RECFM isn't specified in the 
AMP parameter or in the processing program's DCB, V is the default. 

STRNO=number 

specifies the number of request parameter lists the processing program can 
tie up concurrently. Neither VSAM nor the ISAM interface can anticipate 
the number, so you must indicate it in the STRNO parameter. Specify a 
number at least equal to the number of BISAM and QISAM requests that 
your program can issue concurrently. (If you have subtasks, add the 
number of such requests for each subtask together, plus an additional one 
for each subtask that sequentially processes the same data set.) In a create 
step, STRNO cannot be greater than 1. 
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SYN AD =modulename 

specifies the name of a routine that the ISAM interface is to load and exit 
to if a physical or logical error occurs when you are gaining access to the 
key-sequenced data set. If your processing program already indicates a 
SYNAD routine, the routine specified in the AMP SYNAD parameter 
replaces it. 

The ISAM interface uses a request parameter list to describe a request that 
your program issues. The interface uses the same request parameter list over 
and over: 

• With BISAM, a READ for update ties up a request parameter list until a 
WRITE or FREEDBUF is issued (at which time the interface issues an 
ENDREQ for the request parameter list). 

• With QISAM, a request parameter list is tied up until an ESETL is issued 
(at which time the interface issues ENDREQ). 

If the processing program issues an ISAM request when no more request 
parameter lists are available, the ISAM interface returns an ISAM code that 
indicates an invalid request. If you're running subtasks, it's possible to reissue 
the invalid request and have it complete successfully when another subtask 
frees a request parameter list. 

The SYNAD routine must not issue VSAM macros or check for VSAM return 
codes. The ISAM interface translates all VSAM codes to appropriate ISAM 
codes. 

You need not modify or replace a SYNAD routine that issues only a CLOSE, 
ABEND, SYNADAF, or SYNADRLS macro or merely examines DCB or 
DECB exception codes. 



Restrictions in the Use of the ISAM Interface 



Some restrictions were indicated earlier in this chapter that may require you 
to modify an ISAM processing program to process a key-sequenced data set. 
All VS and VSAM restrictions apply to the use of the ISAM interface; for 
example: 

• VSAM doesn't allow the OPENJ macro: if your program issues it, remove 
it or replace it with the OPEN macro. 

• If your processing program was coded on the assumption that the 
indexed-sequential data set it was processing was a temporary data set, you 
may need to modify the program: a VSAM data set cannot be temporary. 

Additional restrictions are: 

• A program must run successfully under ISAM; the interface doesn't check 
for parameters that are invalid for ISAM. 

• If your ISAM program creates dummy records with a maximum key to 
avoid overflow, remove that code for VSAM. 

• If your program counts overflow records to determine reorganization 
needs, its results will be meaningless with VSAM data sets. 

• The work area into which data records are read must not be shorter than a 
record. If your processing program is designed to read a portion of a record 
into a work area, you must change the design. The interface takes the 
record length indicated in the DCB to be the actual length of the data 
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Example: Converting a Data Set 



record. The record length in a BISAM DECB is ignored except when you 
are replacing a variable-length record with the WRITE macro. 

You may share data among subtasks that specify the same DD statement in 
their DCB(s), and VSAM ensures data integrity. But if you share data 
among subtasks that specify different DD statements for the data, you are 
responsible for data integrity. The ISAM interface doesn't ensure DCB 
integrity when two or more DCBs are opened for a data set. Not all of the 
fields in a DCB can be counted on to contain valid information. 

If your processing program issues the SETL I or SETL ID instruction, you 
must modify the instruction to some other form of the SETL or take it out. 
The ISAM interface cannot translate a request that depends on a specific 
block or device address. 

Although asynchronous processing may be specified in an ISAM 
processing program, all ISAM requests are handled synchronously by the 
ISAM interface; WATT and CHECK requests are always satisfied 
immediately. The ISAM CHECK macro doesn't result in a VSAM 
CHECK macro's being issued but merely causes exception codes in the 
DECB (data event control block) to be tested. 

For processing programs that use locate processing, the ISAM interface 
constructs buffers to simulate locate processing. 

For blocked-record processing, the ISAM interface simulates 
unblocked-record processing by setting the overflow-record indicator for 
each record. (In ISAM, an overflow record is never blocked with other 
records.) The ISAM RELSE instruction causes no action to take place. 

If your ISAM SYNAD routine examines information that cannot be 
supported by the ISAM interface (for example, the IOB), specify a 
replacement ISAM SYNAD routine in the AMP parameter of the VSAM 
DD statement. 

Dynamic allocation with TSO (use LOGON PROC). 

CATALOG/DADSM macros in the ISAM processing program must be 
replaced with Access Method Services commands. 



In this example, the indexed-sequential data set to be converted 
(ISAMDATA) is cataloged either in the system catalog or in a VSAM 
catalog. A key-sequenced data set, VSAMDATA, has previously been 
defined in user catalog USERCTLG. Because both the indexed-sequential 
and key-sequenced data set are cataloged, unit and volume information need 
not be specified. 

ISAMDATA contains records flagged for deletion; these records are to be 
kept in the VSAM data set. 

//CONVERT JOB . . . 

//JOBCAT DD DISP=SHR,DSNAME=USERCTLG 

//STEP EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//ISAM DD DISP=OLD,DSNAME=ISAMDATA,DCB=DSORG=IS 

//VSAM DD DISP=OLD,DSNAME=VSAMDATA 

//SYSIN DD * 

REPRO INFILE( ISAM ENVIRONMENT DUMMY ) ) 
OUTFILE(VSAM) 
/* 



140 OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide 



To drop records flagged for deletion in the indexed-sequential data set, omit 
ENVIRONMENT(DUMMY). 



Example: Issuing a SYNADAF Macro 



The following example illustrates how a SYNAD routine specified by way of 
AMP may issue a SYNADAF macro without preliminaries — registers and 1 
already contain what SYNADAF expects to find. 



AMPSYN 



BISAM 



CSECT 
USING *,15 



Register 1 5 contains the entry address 
to AMPSYN. 



SYNADAF ACSMETH=QISAM Either QIS AM or BISAM may be 

specified. 



Load address of next instruction into 
register 7 for base register. 

The address of the DCB is stored 132 
bytes into the SYNADAF message. 

The address of the DECB is stored 128 
bytes into the SYNADAF message. 

Does the DCB indicate QISAM scan? 

Yes. 

Does the DCB indicate QISAM load? 

Yes. 

Does the DECB indicate an invalid 
BISAM request? 

Yes. 

The routine might print the SYNADAF 
message or issue ABEND. 



STM 


14,12, 12( 13) 


BALR 


7,0 


USING 


*,7 


L 


15,132( 1 ) 


L 


14,128( 1 ) 


TM 


42( 15),X'40' 


BO 


QISAM 


TM 


43( 15),X'40' 


BO 


QISAM 


TM 


24( 14),X'10' 


BO 


INVBISAM 



QISAM 



TM 


80( 15),X'10' 


Does the DCB indicate an invalid 
QISAM request? 


BO 


INVQISAM 


Yes. 



The routine might print the SYNADAF 
message or issue ABEND. 

INVBISAM EQU * 

INVQISAM EQU * 

LM 14,12,12(13) 

DROP 7 

USING AMPSYN, 15 

SYNADRLS 

BR 14 

END AMPSYN 

When the processing program closes the data set, the interface issues VSAM 
PUT macros for ISAM PUT locate requests (in load mode), deletes the 
interface routines from virtual storage, frees virtual-storage space that was 
obtained for the interface, and gives control to VSAM. 
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USER-WRITTEN EXIT ROUTINES 



User- written routines may be supplied to: 

• Analyze logical errors 

• Analyze physical errors 

• Perform end-of -data processing 

• Record transactions made against a data set 

• Perform user-security verification 



LERAD Exit Routine to Analyze Logical Errors 



A LERAD routine should examine the feedback field in the request 
parameter list to determine what logical error occurred. What the routine does 
after determining the error depends on your knowledge of the kinds of things 
in the processing program that may have caused the error. After a logical 
error is corrected, return to VSAM. If the error cannot be corrected, close the 
data set and either terminate processing or return to VSAM. 

Figure 21 gives the contents of the registers when VSAM exits to the LERAD 
routine. 

Reg. Contents 

Unpredictable. 

1 Address of the request parameter list that contains the feedback field the routine 
should examine. The register must contain this address if you return to VSAM. 

2-13 Same as when the request macro was issued. Register 13, by convention, contains 

the address of your processing program's 72-byte save area, which may not be 
used as a save area by the LERAD routine if the routine returns control to 
VSAM. 

14 Return address to VSAM. 

15 Entry address to the LERAD routine. The register doesn't contain the 
logical-error indicator. 

Figure 21. Contents of Registers at Entry to LERAD 

If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB and 
returns to VSAM, it must provide a save area and restore registers 13 and 14, 
which are used by these macros. 

If a logical error occurs and no LERAD routine is provided (or the LERAD 
exit is inactive), VSAM returns codes in register 15 and in the feedback field 
of the request parameter list to identify the error. See "Logical Errors" in the 
chapter "Request Macros" for a description of these return codes. 



SYNAD Exit Routine to Analyze Physical Errors 



VSAM exits to a SYNAD routine if a physical error occurs when you request 
access to data. It also exits to a SYNAD routine when you close a data set if a 
physical error occurs while VSAM is writing the contents of a buffer out to 
direct-access storage. 

A SYNAD routine should examine the feedback field in the request 
parameter list to identify the type of physical error that occurred. It should 
then get the address of the message area, if any, from the request parameter 
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list, so that it can examine the message for detailed information about the 
error. 

The main problem with a physical error is the possible loss of data. You 
should try to recover your data before continuing to process. Input operations 
(ACB MACRF=IN) are generally less serious than output or update 
operations (MACRF=OUT), because your request was not attempting to 
alter the contents of the data set. 

If the routine cannot correct an error, it might print the physical-error 
message, close the data set, and terminate the program. If the error occurred 
while VSAM was closing the data set, and if another error occurs after the 
exit routine issues a CLOSE macro, VSAM doesn't exit to the routine a 
second time. 

If the SYNAD routine returns to VSAM, whether the error was corrected or 
not, VSAM drops the request and returns to your processing program at the 
instruction following the last executed instruction. Register 15 is reset to 
indicate that there was an error, and the feedback field in the request 
parameter list identifies it. 

Physical errors affect positioning: if a GET was issued that would have 
positioned VSAM for a subsequent sequential GET and an error occurs, 
VSAM is positioned at the control interval next in key (RPL OPTCD=KEY) 
or in entry (OPTCD=ADR) sequence after the control interval involved in 
the error. The processing program can therefore ignore the error and proceed 
with sequential processing. With direct processing, the likelihood of 
reencountering the control interval involved in the error depends on your 
application. 

Figure 22 gives the contents of the registers when VSAM exits to the SYNAD 
routine. 

Reg. Contents 

Unpredictable. 

1 Address of the request parameter list that contains a feedback return code and 
the address of a message area, if any. If you issued a request macro, the request 
parameter list is the one pointed to by the request macro; if you issued a CLOSE 
macro, the request parameter list was built by VSAM to process the close 
request. Register 1 must contain this address if the SYNAD routine returns to 
VSAM. 

2-13 Same as when the request macro or CLOSE macro was issued. Register 13, by 

convention, contains the address of your processing program's 72-byte save area, 
which may not be used by the SYNAD routine if it returns control to VSAM. 

14 Return address to VSAM. 

15 Entry address to the SYNAD routine. The register doesn't contain the 
physical-error indicator. 

Figure 22. Contents of Registers at Entry to SYNAD 

If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB and 
returns to VSAM, it must provide a save area and restore registers 13 and 14, 
which are used by these macros. 

See "Physical Errors" in the chapter "Request Macros" for the format of a 
physical-error message that can be written by the SYNAD routine. 

If a physical error occurs and no SYNAD routine is provided (or the SYNAD 
exit is inactive), VSAM returns codes in register 15 and in the feedback field 
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Exception Exit Routine 



of the request parameter list to identify the error. See "Physical Errors" in the 
chapter "Request Macros" for a description of these return codes. 



You can provide an exception exit routine to monitor I/O errors associated 
with a data set. The name of your routine is specified via the Access Method 
Services DEFINE command. 

If an I/O error occurs while a program with a specified SYNAD routine is 
processing a data set with a specified exception exit, the exception exit is 
taken first. 

See the appropriate Access Method Services publication for information 
about how exception exits are established, changed, or nullified. 



EODAD Exit Routine to Process End-of-Data 



VSAM exits to an EODAD routine when an attempt is made to sequentially 
retrieve or point to a record beyond the last record in the data set (one with 
the highest key for keyed access and the one with the highest RBA for 
addressed access). (VSAM doesn't take the exit for direct requests that 
specify a record beyond the end.) If the EODAD exit isn't used, the condition 
is considered a logical error (FDBK code X'04') and can be handled by the 
LERAD routine, if one is supplied. 

The typical actions of an EODAD routine are to issue completion messages, 
close the data set, and terminate processing without returning to VSAM. If 
the routine returns to VSAM and another GET request is issued for access to 
the data set, VSAM exits to the LERAD routine. 

If a processing program retrieves records sequentially with a request defined 
by a chain of request parameter lists, the EODAD routine must determine 
whether the end of the data set was reached for the first request parameter 
list in the chain. If not, then one or more records have been retrieved but not 
yet processed by the processing program. 

Figure 23 gives the contents of the registers when VSAM exits to the 
EODAD routine. 

Reg. Contents 

Unpredictable. 

1 Address of the request parameter list that defines the request that occasioned 
VSANfs reaching the end of the data set. The register must contain this address if 
you return to VSAM. 

2-13 Same as when the request macro was issued. Register 13, by convention, contains 

the address of your processing program's 72-byte save area, which may not be 
used as a save area by the EODAD routine if it returns control to VSAM. 

14 Return address to VSAM. 

15 Entry address to the EODAD routine. 
Figure 23. Contents of Registers at Entry to EODAD 

If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB and 
returns to VSAM, it must provide a save area and restore registers 13 and 14, 
which are used by these macros. 

The type of data set whose end was reached can be determined by examining 
the request parameter list for the address of the access-method control block 
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that connects the program to the data set and testing its ATRB 
characteristics. 



JRNAD Exit Routine to Journalize Transactions 



A JRNAD routine can be provided to record transactions against a data set 
and to keep track of changes in the RBAs of records. VSAM takes the 
JRNAD exit each time the processing program issues a GET, PUT, or 
ERASE; each time data is shifted right or left in a control interval or is moved 
to another control interval to accommodate a record's being deleted, inserted, 
shortened, or lengthened; and path time an I/O error occurs. 

Because the JRNAD is taken for I/O errors, a journal exit may zero out, or 
otherwise alter, the physical-error return code, so that a series of operations 
may continue to completion, even though one or more of the operations 
failed. 

Figure 24 gives the contents of the registers when VSAM exits to the JRNAD 
routine. 

If the exit routine issues GENCB, MODCB, SHOWCB, or TESTCB, it must 
restore register 14; which is used by these macros, before it returns to VSAM. 

If the exit routine uses register 1 , it must restore it with the parameter-list 
address before returning to VSAM. (The routine must return for completion 
of the request that caused VSAM to exit.) 

For journalizing transactions (when VSAM exits because of a GET, PUT, or 
ERASE), you can use the SHOWCB macro to display information in the 
request parameter list about the record that was retrieved, stored, or 
deleted— FffiLDS=(AREA,KEYLEN,RBA,RECLEN), for example. You 
can also use the TESTCB macro to find out whether a GET or a PUT was for 
update (OPTCD=UPD). 

For recording RBA changes, you must calculate how many records there are 
in the data being shifted or moved, so you can keep track of the new RBA for 
each one. With fixed-length records, you calculate the number by dividing the 
record length into the number of bytes of data being shifted. With 
variable-length records, you could calculate the number by using a table that 
not only identifies the records (by associating a record's key with its RBA), 
but also gives their length. 

Some control-interval splits involve data being moved to two new control 
intervals, and control-area splits normally involve many control intervals' 
contents being moved. In these cases, VSAM exits to the JRNAD routine for 
each separate movement of data to a new control interval. 

You should provide a routine to keep track of RBA changes caused by 
control-interval and control-area splits. RBA changes that occur by way of 
keyed access to a key-sequenced data set must also be recorded if you intend 
to process the data set later by direct-addressed access. 

If your JRNAD routine only journals transactions it should ignore reason 
X'OC and return to VSAM; conversely, it should ignore reasons X'OO', 
X'04\ and X'08' if it only records RBA changes. 

The JRNAD exit must be indicated as active before the data set for which the 
exit is to be used is opened, and the exit must not be made inactive during 
processing. If you define more than one access-method control block for a 
data set and want to have a JRNAD routine, the first ACB you open for the 
data set must specify the exit list that identifies the routine. 
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Reg. Contents 

Unpredictable. 

1 Address of a parameter list with the following format: 

4 bytes Address of the request parameter list that defines the request that 
caused VSAM to exit to the routine 

4 bytes Address of a 5-byte field that identifies the data set being processed. 
This field has the format: 

4 bytes Address of the access-method control block that is specified 
by the request parameter list that defines the request that 
occasioned the JRNAD exit's being taken 

1 byte Indication of whether the data set is the data (X01') or the 
index (X'02') component 

4 bytes For RB A changes only, the RB A of the first byte of data that is being 
shifted or moved 

4 bytes For RBA changes only, the number of bytes of data that is being 

shifted or moved (this number doesn't include free space, if any, or 
control information — except for a control-area split, when the whole 
contents of a control interval are moved to a new control interval) 

4 bytes For RBA changes only, the RBA of the first byte to which data is 
being shifted or moved 

1 byte Indication of the reason VSAM exited to the JRNAD routine: 

X'OO' GET request 

X'04' PUT request 

X'08' ERASE request 

X'OC RBA change 

X 4 10' Read spanned record segment 

X'14' Write spanned record segment 

X'18' Reserved 

X'lC Reserved 

For shared resources: 1 

X'20' Control area split 

X'24' Input error 

X'28' Output error 

X'2C Buffer write 

1 byte Reserved. 

2-13 Unpredictable. 

14 Return address to VSAM. 

15 Entry address to the JRNAD routine. 

described in OS/VS Virtual Storage Access Method (VSAM Options for Advanced 
Applications. 

Figure 24. Contents of Registers at Entry to JRNAD 



User-Security-Verification Routine 



If you use VSAM password protection, you may also have your own routine 
to check a requester's authority. VSAM transfers control to your routine, 
which must reside in SYS1.LINKLIB, when a requester gives a correct 
password other than the master password. 

You may, through the Access Method Services DEFINE command, identify 
your user security- verification routine (USVR) and associate up to 256 bytes 
of your own security information with each data set to be protected. This 
information — the user security-authorization record (USAR) — is made 
available to the USVR when the routine gets control. You may restrict access 
to the data set as you choose; for example, you may require that the owner of 
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a data set give his ID when he defines the data set and then allow only the 
owner to gain access to the data set. 

Figure 25 gives the contents of the registers when VSAM jnves control to the 
USVR. 

Reg. Contents 

Unpredictable. 

1 Address of a parameter list with the following format: 

44 bytes Name of the data set for which authority to process is to be verified 
(the name you specified when you defined it with Access Method 
Services) 

8 bytes Prompting code (or Os) 

8 bytes Owner identification (or Os) 

8 bytes The password that the requester gave (it has been verified by VSAM) 

2 bytes Length of the USAR (in binary) 

— The USAR 

2-13 Unpredictable. 

1 4 Return address to VSAM. 

1 5 Entry address to the USVR. When the routine returns to VSAM, it indicates by the 
following codes in register IS whether the requester has been authorized to gain 
access to the data set: 

Authority granted 

not Authority withheld 

Figure 25. Communication with User-Security- Verification Routine 
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APPENDIX A: SUMMARY OF MACROS 



For easy reference, the formats of all of the macros described in this book are 
repeated in this one place in alphabetical order. 

BLDVRP, DLVRP, GETDC, MRKBFR, PUTDC, SCHBFR, SHOWCAT, and 
WRTBFR are described in OS/VS Virtual Storage Access Method (VSAM) 
Options for Advanced Applications. 



ACB (Generate an Access-Method Control Block) 



CHECK (Suspend Processing) 



CLOSE (Disconnect Program and Data) 



ENDREQ (Terminate a Request) 



ERASE (Delete a Record) 



[label] 


ACB 


IAM=VSAM] 

[,BSTRNO= number] 

[,BUFND= number] 

[,BUFNI= number] 

[,BUFSP= number] 

[,CATALOG={YES | NO] 

[,CRA={SCRA|UCRA] 

[,DDNAME=dtfname ] 

[,EXLST= address] 

[,MACRF=([ADR][,CNV][,KEY] 
[,CFX|NFX] 
[,DDN | DSN] 
[,DFR|NDF] 
[,DIR][,SE2][,SKP] 
[,ICI | NCI] 
[,IN][,OUT] 
[NIS | SIS] 
[,NRM | AIX] 
[NRSIRST] 
[NSR|LSR|GSR] 
[,NUB | UBF])] 

[M^REA= address] 

[,MLEN= number] 

[,PASSWD= address] 

[,STRNO= number] 



[label] 


CHECK 


RPL= address 



[label] 


CLOSE 


( address [,( options )]...] 
[,TYPE=T] 



[label] 


ENDREQ 


RPL= address 



[label] 


ERASE 


RPL= address 
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EXLST (Generate an Exit List) 



[label] 


EXLST 


[AM=VSAM] 

[,EOD AD=(address[,A | N][,L])] 
[,JXNAD=(address [,A | N][,L])] 
[,LERAD=(address [,A | N][,L])] 
[,SYN AD**(address[,A | N][,L])] 



GENCB (Generate an Access-Method Control Block) 



[label] 


GENCB 


BLK=ACB 

[,AM=VSAM] 

[,BSTRNO= number] 

[,BUFND= number] 

[,BUFNI= number] 

[,BUFSP= number] 

[,CATALOG={YES | NO] 

[,COPIES=/i wmter] 

[,CRA={SCRA|UCRA] 

[,DDNAME=ddname ] 

[,EXLST= address] 

[,LENGTH= number] 

[,MACRF=([ADR][,CNV][,KEY] 
[,CFX | NFX] 
[,DDN | DSN] 
[,DFR|NDF] 
[,DIR][,SE2][,SKP] 
[,ICI | NCI] 
[,IN][,OUT] 
[,NIS | SIS] 
[,NRM | ADC] 
[,NRS | RST] 
[,NSR | LSR | GSR] 
[,NUB | UBF])] 

[,MAREA= address ] 

[,MLEN= number] 

[,PASSWD= address] 

[,STRNO= address] 

[,WXREA= address] 



GENCB (Generate an Exit List) 



[label] 


GENCB 


BLK« EXLST 
l,AM=VSAM] 

[,COPIES= m/mZ*?r] 
lEODADMaddress [,A | N][,L])] 
[JKNAD=(address [,A | N][,L])] 
[,LENGTH=* number] 
[&ERAD=(address [,A | N][,L])] 
[,SYNAD=( address [,A | N][,L])] 
[,WAREA= address] 
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GENCB (Generate a Request Parameter List) 



[label] 


GENCB 


BLK=RPL 

[,ACB= address] 

[,AM=VSAM] 

[, ARE A= address] 

[, AREALEN = number ] 

[,ARG= address] 

[,COPIES= number] 

[,ECB= address] 

[,KEYLEN= number] 

[,LENGTH= number] 

[,MSGAREA= address ] 

[,MSGLEN= number] 

[,NXTRPL= address] 

[,OPTCD=([ADR | CNV | KEY] 
[,DIR \ SEQ | SKP] 
[ARD|LRD] 
[FWD | BWD] 
[,ASY | SYN] 
[,NSP|NUP|UPD] 
[,KEQ | KGE] 
[,FKS | GEN] 
[,LOC | MVE])] 

[,RECLEN= number] 

[,TRANSID= number] 

[,WAREA= address] 
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GET (Retrieve a Record) 



MODCB (Modify an Access-Method Control Block) 



[label] 


GET 


RPL= address 



[label] 


MODCB 


ACB= address 

[,BSTRNO= number] 

[,BUFND= number] 

[,BUFNI= number] 

[,BUFSP= number] 

[,CATALOG={YES | NO] 

[,CRA={SCRA|UCRA] 

[,DDNAME=ddname ] 

[,EXLST= address] 

[,MACRF=([ADR][,CNV][,KEY] 
[,CFX | NFX] 
[,DDN | DSN] 
[,DFR | NDF] 
[,DIR][,SEQ][,SKP] 
[ICI | NCI] 
[,IN][,OUT] 
[,NIS | SIS] 
[,NRM | AIX] 
[,NRS | RST] 
[,NSR | LSR | GSR] 
[,NUB | UBF])] 

[,MAREA=adWres$] 

[,MLEN= number] 

[,PASSWD= address] 

[,STRNO= number] 



MODCB (Modify an Exit List) 



[label] 


MODCB 


EXLST= address 
[,EOD AD=(address[,A \ N][,L])] 
[,JRNAD=(a^/rm [,A | N][,L])] 
[,LERAD=(address [,A | N][,L])] 
[,SYNAD=(address [,A | N][,L])] 
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MODCB (Modify a Request Parameter List) 



[label] 


MODCB 


RPL= address 

[,ACB= address] 

[, ARE A= address] 

[,AREALEN= number] 

[,ARG= address] 

[,ECB= address] 

[,KEYLEN= number] 

[,MSGAREA= address ] 

[,MSGLEN= number] 

[,NXTRPL= address ] 

[,OPTCD=([ADR | CNV | KEY] 
[,ARD | LRD] 
[,FWD | BWD] 
[,DK|SEQ|SKP] 
[,ASY | SYN] 
[,NSP|NUP|UPD] 
[,KEQ | KGE] 
[,FKS | GEN] 
[,LOC | MVE]) 

[,RECLEN= number ] 

[,TRANSID= number] 
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OPEN (Connect Program and Data) 



POINT (Position for Access) 



PUT (Store a Record) 



RPL (Generate a Request Parameter List) 



[label] 


OPEN 


(address [^options )]...) 



[label] 


POINT 


RPL= address 



[label] 


PUT 


RPL= address 



[label] 


RPL 


ACB= address 

[,AM=VSAM] 

[, ARE A= address] 

[,AREALEN= number ] 

[,ARG= address] 

[,ECB= address] 

[,KEYLEN= number] 

[,MSGAREA= address ] 

[,MSGLEN= number ] 

[,NXTRPL= address] 

[,OPTCD=([ADR | CNV | KEY] 
[,DIR1SEQ|SKP] 
[,ARD | LRD] 
[,FWD | BWD] 
[,ASY | SYN] 
[,NSP|NUP|UPD] 
[,KEQ | KGE] 
[,FKS|GEN] 
[,LOC | MVEJ)] 

[,RECLEN= number ] 

[,TRANSID= number ] 



SHOWCB (Display Fields of an Access-Method Control Block) 



[label] 


SHOWCB 


ACB— address 

,AREA= address 

,LENGTH= number 

[,OBJECT-{DATA | INDEX] 

,FIELDS=([,ACBLEN][,AVSPAC][,BFRFND] 
[,BSTRNO][,BUFND][,BUFNI] 
[,BUFNO][,BUFRDS][,BUFSP] 
[,CINV][,DDNAME1[,ENDRBA] 
[,ERROR][,EXLST][,FS] 
[,KEYLEN][,LRECL][,MAREA] 
[,MLEN][,NCIS][,NDELR] 
[,NEXCP][,NEXT][,NINSR] 
[,NIXL][,NLOGR][,NRETR] 
[NSSS][,NUIW][,NUPDR] 
[,PASSWD][,RKP][,STMST] 
[,STRMAX][,STRNO][UIW]) 
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SHOWCB (Display Fields of an Exit List) 



[label] 


SHOWCB 


AR£A= address 

,EXLST= address 

,FIELDS«([EODAD][,EXLLEN][,JRNAD] 

[,LERAD][,SYNAD]) 
,LENGTH= number 



SHOWCB (Display Fields of a Request Parameter List) 



[label] 


SHOWCB 


AREA=: address 

,FIELDS=([ACB][,AIXPC][,AREA][,AREALEN] 
[,ARG][,ECB][,FDBK][,FTNCD] 
[,KEYLEN][,MSGAREA] 
[,MSGLEN][,NXTRPL][,RBA] 
[,RECLEN][,RPLLEN][,TRANSID] 

,LENGTH= number 

,RPL= address 
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TESTCB (Test a Field of an Access-Method Control Block) 



[label] 



TESTCB 



ACB= address 

[,ERET= address] 

[,OBJECT=DATA | INDEX] 

, { ATRB = ([ESDS][,KSDS][,REPL][,RRDS] 

[,SPAN][,SSWD][,UNQ][,WCK]) | 
CATALOG={YES | NO} | 
MACRF=([ADR][,AIX][,CFX][,CNV][,DDN] 
[,DFR][,DIR][,DSN][,GSR][,ICI] | 

[,IN][,KEY][,LSR][,NCI][,NDF] | 
[,NFX][,NIS],NRM][,NRS][,NSR] | 
[,NUB][,OUT][,SEQ][SIS][,SKP] | 
[,UBF] | 

OFLAGS=OPEN | 

OPENOBJ={PATH | BASE | ATX} | 

ACBLEN= number \ 

AVSPAC= number \ 

BSTRNO= number \ 

BUFND= number \ 

BUFNI= number | 

BUFNO= number \ 

BUFSP= number | 

CINV= number | 

DDNAME=ddname \ 

ENDRBA= number \ 

ERROR= number | 

EXLST= address \ 

FS= number \ 

KEYLEN= number \ 

LRECL= number \ 

MAREA= address \ 

MLEN= number \ 

NCIS= number \ 

NDELR= number \ 

NEXCP= number \ 

NEXT= number \ 

NINSR= number \ 

N1XL= number \ 

NLOGR= number \ 

NRETR= number | 

NSSS= number | 

NUPDR= number \ 

PASSWD= address \ 

RKP= number \ 

STMST= address \ 

STRNO= number] 
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TESTCB (Test a Field of an Exit List) 



[label] 


TESTCB 


,EXLST= address 

[,ERET= address] 

{EODAD={0 1 ([address][ f A | N][,L])} 1 
JRNAD={0 1 {[address][,A | N][,L])} | 
LERAD={0 1 ([address][,A | N][,L])} | 
SYNAD={0 | ([address]lA | N][,L])}} 
[,EXLLEN= number ] 



TESTCB (Test a Field of a Request Parameter List) 



[label] 


TESTCB 


RPL= address 
[,ERET= address] 
{IO=COMPLETE | 

OPTCD=([ADR][,ARD][,ASY][,BWD][,CNV] 
[,DIR][,FKS][,FWDH,GEN][,KEQ] 
[,KEY][,KGE],LOC][,LRD][,MVE] 
[,NSP][,NUP][,SEQ][,SKP][,SYN] 
[,UPD])| 

RBA= number \ 

RECLEN= number \ 

RPLLEN= number \ 

ACB= address \ 

ArXFLAG=AIXPKP| 

AIXPC= number \ 

ARE A= address \ 

AREALEN= number \ 

ARG= address \ 

ECB= address \ 

FDBK= number \ 

FTNCD= number | 

KEYLEN=/wmter | 

MSGAREA= address \ 

MSGLEN= number \ 

NXTRPL= address | 

TRANSID= number ] 
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APPENDIX B: LIST, EXECUTE, AND GENERATE 
FORMS OF GENCB, MODCB, SHOWCB, AND 
TESTCB 



List-Form Keyword 



The standard forms of the GENCB, MODCB, SHOWCB, and TESTCB 
macros build a parameter list describing in codes the actions indicated by the 
operands you specify and pass the list to VSAM to take the indicated action. 
The list, execute, and generate forms of GENCB, MODCB, SHOWCB, and 
TESTCB allow you to write reentrant programs, share parameter lists, and to 
modify a parameter list before using it. 

Following is a brief description of the list, execute, and generate forms: 

• The list form is used to build the parameter list either inline (referred to as 
simple list) or in an area remote from the macro expansion (referred to as 
remote list). Both the simple- and the remote-list forms allow you to build 
a single parameter list that can be shared. 

• The execute form is used to modify a parameter list and to pass it to 
VSAM for action. 

• The generate form is used to build the parameter list in a remote area and 
to pass it to VSAM for action. 

The list, execute, and generate forms of the GENCB, MODCB, SHOWCB, 
and TESTCB macros have the same format as the standard forms, with the 
exception of: 

• An additional keyword, MF 

• Some operands' being optional or not allowed 

The sections that follow describe the format of the MF keyword and the use 
of list, execute, and generate forms. They indicate the optional and required 
operands. 



The format of the MF keyword for the list form is: 

MF= {L | (L, address [, label ])} 
where: 

L 

specifies that this is the list form of the macro. 

address 

specifies the address of a remote area in which the parameter list is to be 
built. The area must begin on a fullword boundary. You can specify the 
address in register notation or as an expression valid for a relocatable 
A-type address constant or a direct or indirect S-type address constant. 

label 

is a unique name that is used in an EQU instruction in the expansion of the 
macro; label is equated to the length of the parameter list. You do not have 
to know the length of the parameter list if you code label; the expansion of 
the macro determines the amount of storage required. 
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Execute-Form Keyword 



Because the MF=L expansion does not include executable code, register 
notation and expressions that generate S-type address constants cannot be 
used. 

If you code MF=L, the parameter list is built inline, which means that the 
program is not reentrant if the parameter list is modified at execution. 

If you code MF=(L,address), the parameter list is built in the remote area 
specified, and the area must be large enough for the parameter list. 

The size, in fullwords, of a parameter list is: 

• For GENCB, 4, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For MODCB, 3, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For SHOWCB, 5, plus 2 times the number of fields specified in the 
FIELDS operand 

. For TESTCB, 8 (plus 1 for DDNAME, STMST, EODAD, JRNAD, 
LERAD, or SYNAD) 

If you code MF=(L,address,label), the parameter list is built in the remote 
area specified. The expansion of the macro equates label with the length of 
the parameter list. 



The format of the MF keyword for the execute form is: 

MF=(E,address) 
where: 

E 

specifies that this is the execute form of the macro. 

address 

is the address of the parameter list. 

The expansion of the execute form of the macro results in executable code 
that causes: 

1. A parameter list to be modified if requested 

2. Control to be passed to a routine that satisfies the request 

You may not use the execute form to add an entry to a parameter list. If you 
try to add an entry, an error code of 8 is returned to you in register 15. 
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Generate-Form Keyword 



The format of the MF keyword for the generate form is: 

MF= (G, address [, label ]) 
where: 



specifies that this is the generate form of the macro. 

address 

specifies the address of a remote area in which the parameter list is to be 
built. The area must begin on a fullword boundary. 

label 
is a unique name that is used in an EQU instruction in the expansion of the 
macro; label is equated to the length of the parameter list. You do not have 
to know the length of the parameter list if you code label; the expansion of 
the macro determines the amount of storage required. 

If you code MF»(G,address), the parameter list is built in the remote area 
specified. 

If you code MF=(G,address,label), the parameter list is built in the remote 
area specified. The expansion of the macro equates the length of the 
parameter list to label. 



Optional and Required Operands 



list Form of GENCB 



Keywords that are required in the standard forms of the GENCB, MODCB, 
SHOWCB, and TESTCB macros may be optional in the list, execute, and 
generate forms or may not be allowed in the execute form. The meaning of 
the keywords, however, and the notation that may be used to express 
addresses, names, numbers, and option codes are the same. See the chapter 
"Control Block Macros" for the meaning of keywords. See "Appendix C: 
Operand Notation for GENCB, MODCB, SHOWCB, and TESTCB" for an 
explanation of how operands may be coded. 



The format of the list form of GENCB is: 



[label] 


GENCB 


BLK={ ACB | EXLST | RPL} 

[,AM=VSAM] 

[,COPIES= number] 

[, keyword ={ address \name \ number \ option },...] 

[,LENGTH= number ] 

,MF= {L | (L, address [, label ])} 

[,WAREA= address] 
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Execute Form of GENCB 



Generate Form of GENCB 



List Form of MODCB 



Execute Form of MODCB 



Generate Form of MODCB 



The format of the execute form of GENCB is: 



[label] 


GENCB 


_____ _ _ . 

BLK-{ACB | EXLST | RPL} 

[,AM-VSAM] 

[COPIES- number] 

[, keyword — { address \ name | number \ option },...] 

[,LENGTH- number ] 

,MF**(R*address) 

[,W AREA- address] 



The format of the generate form of the GENCB macro is: 



[label] 


GENCB 


BLK-{ACB | EXLST | RPL} 

[,AM«VSAM] 

[,COPIES- number] 

[, keyword — { address | name \ number \ option },...] 

[,LENGTH« number ] 

,MF- (G, address [, label ]) 

[,W AREA- address] 



The format of the list form of MODCB is: 



[label] 


MODCB 


{ACB | EXLST | RPL}- address 

, keyword — { address \name \ number \ option},... 

,MF={L\(L,address[,labeI])} 



The format of the execute form of MODCB is: 



[label] 


MODCB 


[{ACB | EXLST | RPL} - address ] 

[, keyword — { address \ name \ number \ option },...] 

,MF=(E,address) 



The format of the generate form of MODCB is: 



[label] 


MODCB 


{ACB | EXLST | RPL} - address 

, keyword — { address \name \ number {option],.... 

,MF- (G, address [, label ]) 
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List Form of SHOWCB 



The format of the list form of SHOWCB is: 



[label] 


SHOWCB 


[{ ACB | EXLST | RPL} = address ] 

,AREA= address 

,FIELDS= (keyword [, keyword ,...]) 

,LENGTH= number 

,MF= {L | (L, address [, label ])} 

[,OBJECT={DATA | INDEX] 



Execute Form of SHOWCB 



The format of the execute form of SHOWCB is: 



[label] 


SHOWCB 


[{ACB | EXLST | RPL} = address ] 
, AREA= address 
,MF=(E, address) 
[,OBJECT={DATA | INDEX] 



Generate Form of SHOWCB 



The format of the generate form of SHOWCB is: 



[label] 


SHOWCB 


[{ACB | EXLST | RPL} = address ] 
,AREA= address 

t ¥lELDS-(Jceyword [, keyword ,...]) 
,LENGTH= number 
,MF= (G, address [, label ]) 
[,OBJECT={DATA | INDEX] 



List Form of TESTCB 



The format of the list form of TESTCB is: 



[label] 


TESTCB 


[{ACB | EXLST | RPL} - address ] 
[,ERET= address] 

, keyword= { address \ name \ number \ option } 
,MF» {L | (L, address [, label ])} 
[,OBJECT-{DATA | INDEX] 



Execute Form of TESTCB 



The format of the execute form of TESTCB is: 



[label] 


TESTCB 


[{ACB | EXLST | RPL} > address ] 

[,ERET= address] 

[, keyword ={ address [name \number \ 

option ] 
,ME**(&address) 
[,OBJECT-{DATA | INDEX] 
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Generate Form of TESTCB 



The format of the generate form of TESTCB is: 



[label] 


TESTCB 


[{ ACB | EXLST | RPL} = address ] 
[,ERET= address] 

, keyword = { address \ name \ number \ option } 
,MF=(G, address [, label ]) 
[,OBJECT={DATA | INDEX] 



Use of List, Execute, and Generate Forms 



Example: Generate Form 



Again, the list, execute, and generate forms allow you to use GENCB, 
MODCB, SHOWCB, and TESTCB in reentrant programs and allow you to 
share parameter lists. Figure 26 indicates which forms of these macros should 
be used in reentrant/nonreentrant and shared/nonshared environments. 



Reentrant 

Shared MF '-(L address Uabel]) 

MF-i&address) 

Nonshared MF«(G, address [, label]) 

Figure 26. Reentrant Programming 



Nonreentrant 

MF=L 

MF=(E,address) 

StandardForm 



The figure shows that: 

• To share parameter lists in a reentrant program, the remote-list form 
should be used in conjunction with the execute form. 

• To share parameter lists in a nonreentrant program, the simple-list form 
should be used in conjunction with the execute form. 

• If you do not intend to share parameter lists, the generate form should be 
used in reentrant programs and the standard form should be used for 
nonreentrant programs. 

The examples that follow illustrate how the list, execute, and generate forms 
work. 



In this example, the generate form of GENCB is used to create a default 
request parameter list in a reeentrant environment. 



LA 10,LEN1 

GETMAIN R,LV=( 10) 



LR 



2,1 



Get length of the parameter list. 

Get storage for the area in which the 
parameter list is to be built. 

Save address of parameter-list area. 



GENCB BLK=RPL, 

MF=(G,(2),LEN1 ) 

The macro expansion equates LEN1 to the length of the parameter list, as 
follows: 

+LEN1 EQU 16 
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Example: Remote-List Form 



In this example, the remote-list form of MODCB is used to build a parameter 
list that will later be used to modify the MACRF bits in an access-method 
control block. 



LA 8 , LEN2 

GETMAIN R,LV=(8) 



LR 3,1 

MODCB ACB=ANYACB , 

MACRF=(KEY,DIR), 
MF=(L,(3),LEN2) 



Get length of the parameter list. 

Get storage for the area in which the 
parameter list is to be built. 

Save address of the parameter-list area. 



The macro expansion equates the length of the parameter list to LEN2, as 
follows:. 

+LEN2 EQU 24 

Example: Execute Form 

In this example, the execute form of MODCB is used to modify the address 
of the access-method control block and MACRF codes in the parameter list 
created by the remote-list form of MODCB in the previous example. 

MODCB ACB=MYACB , MACRF= ( ADR , SEQ , OUT ) , MF= ( E , ( 3 ) ) 

Example: Simple-List and Execute Forms 

In this example, the execute form of TESTCB is used to modify a field that 
was not specified in the list-form TESTCB. 

TESTCB SYNAD=( , A) ,MF=( E,PLIST1 ) 

Constants 

PLIST1 TESTCB EXLST=EXL1 ,LERAD=( LOGERR, A ) ,MF=L 

The second TESTCB macro is in simple-list form, which causes a parameter 
list to be built inline. Because the second TESTCB does not include a 
SYNAD keyword, the first TESTCB, which is in execute form, cannot find a 
SYNAD entry in the parameter list; a return code of 8 is returned in register 
15. 
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APPENDIX C: OPERAND NOTATION FOR 
GENCB, MODCB, SHOWCB, AND TESTCB 



The addresses, names, numbers, and options required with operands in 
GENCB, MODCB, SHOWCB, and TESTCB can be expressed in a variety of 
ways: 

• An absolute numeric expression, for example, STRNO=»=3 and 
COPffiS=10 

• A character string, for example, DDNAME-DATASET 

• A code or a list of codes separated by commas and enclosed in 
parentheses, for example, OPTCD=KEY or OPTCD«(KEY,DB*,IN) 

• An expression valid for a relocatable A-type address constant, for example, 
AREA-MYAREA+4 

• A register from 2 through 12 that contains an address or numeric value, for 
example, SYNAD=(3); equated labels can be used to designate a register, 
for example, SYNAD=(ERR), where the following equate statement has 
been included in the program: ERR EQU 3 

• An expression of the form (S,scon), where scon is an expression valid for 
an S-type address constant, including the base-displacement form 

• An expression of the form (*,scon), where scon is an expression valid for 
an S-type address constant, including the base-displacement form; the 
address specified by scon is indirect, that is, it is the address of an area that 
contains the value of the keyword 

If an indirect S-type address constant is used, the value it points to must meet 
the following criteria: 

• If it is a numeric quantity or an address, it must occupy a fullword of 
storage. 

• If it is an alphameric character string, it must occupy two words of storage, 
be left aligned, and be filled on the right with blanks. 

The expressions that can be used depend on the keyword specified. 
Additionally, register and S-type address constants cannot be used when 
MF=L is specified. See "Appendix B: List, Execute, and Generate forms of 
GENCB, MODCB, SHOWCB, and TESTCB." 
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Operands with GENCB 



Figure 27 shows the expressions that can be used in the GENCB macro. 
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Figure 27. GENCB Operands 
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Operands with MODCB 



Figure 28 shows the expressions that can be used in the MODCB macro. 
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Figure 28. MODCB Operands 
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Operands with SHOWCB 

Figure 29 shows the expressions that can be used in the SHOWCB macro. 
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Figure 29. SHOWCB Operands 
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Operands with TESTCB 



Figure 30 shows the expressions that can be used in the TESTCB macro. 
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GLOSSARY 



The following terms are defined as they are used in this book. 
If you do not find the term you are looking for, refer to the 
index or to the IBM Data Processing Glossary, GC20-1699. 

Access Method Services: A multifunction service program that 
is used to define VSAM data sets and allocate space for them, 
convert indexed-sequential data sets to key-sequenced data 
sets, modify data-set attributes in the catalog, reorganize data 
sets, facilitate data portability between operating systems, 
create backup copies of data sets, help make inaccessible data 
sets accessible, list the records of data sets and catalogs, 
define and build alternate indexes, and convert OS catalogs 
to OS/VS2 catalogs. 

addressed-direct access: The retrieval or storage of a data 
record identified by its RBA, independent of the record's 
location relative to the previously retrieved or stored 
record. (See also keyed-direct access, addressed-sequential 
access, and keyed-sequential access.) 

addressed-sequential address: The retrieval or storage of a data 
record in its entry sequence relative to the previously 
retrieved or stored record. (See also keyed-sequential access, 
addressed-direct access, and keyed-direct access.) 

alternate index: A collection of index entries organized by the 
alternate keys of its associated base data records. It provides 
an alternate means of locating records in the data component 
of a cluster on which the alternate index is based. 

alternate key: One or more consecutive characters taken from 
a data record and used to build an alternate index or to locate 
one or more base data records via an alternate index. (See 
also generic key, key, key field, and prime key.) 

attentate index cluster: The data and index components of an 
alternate index. 

application: As used in this publication, the use to which an 
access method is put or the end result that it serves; 
contrasted to the internal operation of the access method. 

base cluster: A key-sequenced or entry-sequenced data set 
over which one or more alternate indexes are built. 

catalog: (See master catalog and user catalog.) 

catalog recovery area: (See CRA.) 

cluster: A named structure consisting of a group of related 
components (e. g. a data component with its index 
component). A cluster may consist of a single component. 
(See also base cluster and alternate-index cluster.) 

collating sequence: An ordering assigned to a set of items, such 
that any two sets in that assigned order can be collated. As 
used in this publication, the order defined by the System/370 
8-bit code for alphabetic, numeric, and special characters. 

component: A named, cataloged collection of stored records. 
A component, the lowest member of the hierarchy of data 
structures that can be cataloged, contains no named subsets. 

control area: A group of control intervals used as a unit for 
formatting a data set before adding records to it. Also, in a 
key-sequenced data set, the set of control intervals pointed to 
by a sequence-set index record; used by VSAM for 
distributing free space and for placing a sequence-set index 
record adjacent to its data. 



control-area spBt: The movement of the contents of some of 
the control intervals in a control area to a newly created 
control area, to facilitate the insertion or lengthening of a 
data record when there are no remaining free control 
intervals in the original control area. 

control interval: A fixed-length area of auxiliary-storage space 
in which VSAM stores records. It is the unit of information 
transmitted to or from auxiliary storage by VSAM. 

control-interval access: The retrieval or storage of the contents 
of a control interval. 

control-interval spHt: The movement of some of the stored 
records in a control interval to a free control interval, to 
facilitate the insertion or lengthening of a record that won't 
fit in the original control interval. 

CRA: Catalog recovery area. An entry-sequenced data set 
that exists on each volume owned by a recoverable catalog, 
including the catalog itself. The CRA contains self-describing 
records that are duplicates of catalog records that describe 
the volume. 

data integrity: Preservation of data or programs for their 
intended purpose. As used in this publication, the safety of 
data from inadvertent destruction or alteration. 

data record: A collection of items of information from the 
standpoint of its use in an application, as a user supplies it to 
VSAM for storage. 

data security: Prevention of access to or use of data or 
programs without authorization. As used in this publication, 
the safety of data from unauthorized use, theft, or purposeful 
destruction. 

data set: The major unit of data storage and retrieval in the 
operating system, consisting of data in a prescribed 
arrangement and described by control information to which 
the system has access. As used in this publication, a collection 
of fixed- or variable-length records in auxiliary storage, 
arranged by VSAM in key sequence or in entry sequence. 
(See also key-sequenced data set and entry-sequenced data 
set.) 

data space: A storage area defined in the volume table of 
contents of a direct-access volume for the exclusive use of 
VSAM to store data sets, indexes, and catalogs. 

direct access: The retrieval or storage of data by a reference to 
its location in a data set rather than relative to the previously 
retrieved or stored data. (See also addressed-direct access 
and keyed-direct access.) 

distributed free space: Space reserved within the control 
intervals of a key-sequenced data set for inserting new 
records into the data set in key sequence; also, whole control 
intervals reserved in a control area for the same purpose. 

entry sequence: The order in which data records are physically 
arranged (according to ascending RBA) in auxiliary storage, 
without respect to their contents. (Contrast to key sequence.) 

entry-sequenced data set: A data set whose records are 
loaded without respect to their contents, and whose RBAs 
cannot change. Records are retrieved and stored by addressed 
access, and new records are added at the end of the data set. 
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field: In a record or a control block, a specified area used for 
a particular category of data or control information. 

generic key: A high-order portion of a key, containing 
characters that identify those records that are significant for a 
certain application. For example, it might be desirable to 
retrieve all records whose keys begin with the generic key AB, 
regardless of the full key values. 

index: As used in this publication, an ordered collection of 
pairs, each consisting of a key and a pointer, used by VSAM 
to sequence and locate the records of a key-sequenced data 
set. 

index record: A collection of index entries that are retrieved 
and stored as a group. (Contrast to data record.) 

ISAM Interface: A set of routines that allow a processing 
program coded to use ISAM (indexed-sequential access 
method) to gain access to a key-sequenced data set. 

job catalog: A catalog made available for a job by means of 
the JOBCAT DD statement. 

key: One or more characters within an item of data that are 
used to identify it or control its use. As used in this 
publication, one or more consecutive characters taken from a 
data record, used to identify the record and establish its order 
with respect to other records. (See also key field and generic 
key.) 

key field: A field located in the same position in each record 
of a data set, whose contents are used for the key of a record. 

key sequence: The collating sequence of data records, 
determined by the value of the key field in each of the data 
records. May be the same as, or different from, the entry 
sequence of the records. 

key-sequenced data set: A data set whose records are loaded in 
key sequence and controlled by an index. Records are 
retrieved and stored by keyed access or by addressed access, 
and new records are inserted in the data set in key sequence 
by means of distributed free space. RBAs of records can 
change. 

keyed-direct access: The retrieval or storage of a data record 
by use of either an index that relates the record's key to its 
relative location in the data set or a relative record number, 
independent of the record's location relative to the previously 
retrieved or stored record. (See also addressed-direct access, 
keyed-sequential access, and addressed-sequential access.) 

keyed-sequential access: The retrieval or storage of a data 
record in its key or relative record sequence relative to the 
previously retrieved or stored record, as defined by the 
sequence set of an 

index. (See also addressed-sequential access, keyed-direct 
access, and addressed-direct access.) 

master catalog: A catalog that contains extensive data-set and 
volume information that VSAM requires to locate data sets, 
to allocate and deallocate storage space, to verify the 
authorization of a program or operator to gain access to a 
data set, and to accumulate usage statistics for data sets. 

password: A unique string of characters stored in a catalog 
that a program, a computer operator, or a terminal user must 
supply to meet security requirements before a program gains 
access to a data set. 

path: A named, logical entity composed of one or more 
clusters (an alternate index and its base cluster, for example). 



physical record: A physical unit of recording on a medium. For 
example, the physical unit between address markers on a 
disk. 

potater: An address or other indication of location. For 
example, an RBA is a pointer that gives the relative location 
of a data record or a control interval in the data set to which 
it belongs. 

portability: The ability to use VSAM data sets with different 
operating systems. Volumes whose data sets are cataloged in 
a user catalog can be demounted from storage devices of one 
system, moved to another system, and mounted on storage 
devices of that system. Individual data sets can be transported 
between operating systems using Access Method Services. 

prune index: The index component of a key-sequenced data 
set that has one or more alternate indexes. (See also index 
and alternate index.) 

prime key: (See key.) 

random access: (See direct access.) 

RBA: Relative byte address. The displacement of a data 
record or a control interval from the beginning of the data set 
to which it belongs; independent of the manner in which the 
data set is stored. 

record: (See index record, data record, stored record.) 

recoverable catalog: A catalog defined with the recoverable 
attribute. Duplicate catalog entries are put into CRAs that 
can be used to recover data in the event of catalog failure. 
(See also CRA.) 

relative byte address: (See RBA.) 

relative record data set: A data set whose records are loaded 
into fixed-length slots. 

relative record number: A number that identifies not only the 
slot, or data space, in a relative record data set but also the 
record occupying the slot. Used as the key for keyed access to 
a relative record data set. 

replication: (See index replication.) 

reusable data set: A VSAM data set that can be reused as a 
work file, regardless of its old contents. Must not be a base 
cluster. 

RPL string: A set of chained RPLs (the set may contain one or 
more RPLs) used to gain access to a VSAM data set by action 
macros (GET, PUT, etc). Two or more RPL strings may be 
used for concurrent direct or sequential requests made from a 
processing program or its subtasks. 

security: (See data security.) 

sequence cbeckmg: The process of verifying the order of a set 
of records relative to some field's collating sequence. 

sequence set: The lowest level of the index of a key-sequenced 
data set; it gives the locations of the control intervals in the 
data set and orders them by the key sequence of the data 
records they contain. The sequence set and the index set 
together comprise the index. 

sequential access: The retrieval or storage of a data record in 
either its entry sequence, its key sequence or its relative 
record number sequence, relative to the previously retrieved 
or stored record. (See also addressed-sequential access and 
keyed-sequential access.) 
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shared resources: A set of functions that permit the sharing of 
a pool of I/O-related control blocks, channel programs, and 
buffers among several VSAM data sets open at the same 
time. 

skip-sequential access: Keyed-sequential retrieval or storage of 
records here and there throughout a data set, skipping 
automatically to the desired record or collating position for 
insertion: VSAM scans the sequence set to find a record or a 
collating position. Valid for processing in ascending 
sequences only. 

spanned record: A logical record whose length exceeds control 
interval length, and as a result, crosses, or spans, one or more 
control interval boundaries within a single control area. 

step catalog: A catalog made available for a step by means of 
the STEPCAT DD statement. 

stored record: A data record, together with its control 
information, as stored in auxiliary storage. 

upgrade set: All the alternate indexes that VSAM has been 
instructed to update whenever there is a change to the data 
component of the base cluster. 

user catalog: An optional catalog used in the same way as the 
master catalog and pointed to by the master catalog. It also 
lessens the contention for the master catalog and facilitates 
volume portability. 

vertical pofaiter: A pointer in an index record of a given level 
that gives the location of an index record in the next lower 
level or the location of a control interval in the data set 
controlled by the index. 
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INDEX 



For additional information about any subject listed in this 
index, refer to the publications that are listed under the same 
subject in either OS/VS1 Master Index, GC24-5104, or 
OS/VS2 Master Index, GC28-0693. 

This index makes no page references to the glossary. 
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exit list 90 
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control-interval access 
password 34 
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specifying in the macros 49,56 
control-interval split, recording RBA changes for 146 
conventions, notational 3 
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example 140 

indexed-sequential data sets 134 
COPIES operand, in GENCB macro 

copies of access-method control blocks 60 
copies of exit lists 64 
copies of request parameter lists 67 
CRA operand 

in ACB macro 47 
in GENCB macro 60 
in MODCB macro 71 
in TESTCB macro 87 
CROPS subparameter, in AMP parameter 32 

D 

data buffer, specifying space for 45,47,59 
data I/O buffers 45,47,59 
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checkpoint/restart 32 

passwords 34 
DATA option, in OBJECT operand 75,87 
data security 

authorization routine 147 

passwords 34 
data set 
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relative record 17 

reusing 16 
DCB fields supported by ISAM interface 136 
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DDN option, in MACRF operand 44 
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DDNAME operand 
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in FIELDS operand 76 

in GENCB macro 60 

in MODCB macro 71 

in TESTCB macro 86 
DDNAME parameter, in JCL 30 
DEB fields supported by ISAM interface 134 
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deleting a record 
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in MACRF operand 49 
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direct access 
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exit list 80 
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DLVRP macro 149 
DSN option, in MACRF operand 49 
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DSNAME parameter, in JCL 30 
DUMMY parameter, in JCL 30 
duplicate keys 19 
dynamic string extension 45,49 
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ECB operand 

in FIELDS operand 83 

in GENCB macro 67 

in MODCB macro 74 

in RPL macro 54 

in TESTCB macro 92 
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end of data set, method of indicating 37 
end-of -data set processing 145 
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ENDRBA operand 

in FIELDS operand 78 
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examples 127 
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compared to a key-sequenced and a relative record data 
set 18 

definition 16 
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marking records inactive 119 
EODAD exit routine 

coding 145 

contents of registers at entry 145 

handling end-of-data-set processing 145,146 

specifying the exit with EXLST macro 5 1 
EODAD operand 

in EXLST macro 51 

in FIELDS operand 80 
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ERET operand, in TESTCB macro 
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error exit routine 
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ERROR operand 

in FIELDS operand 76 

in TESTCB macro 86 
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from alternate index upgrade requests 97 
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fields in access-method control block 75 
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example 165 
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changing 72 
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EODAD 145 

exception exit 97 
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in FIELDS operand 76 
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FDBK field, in request parameter list 
displaying 

fields in access-method control block 76 
fields in exit list 80 
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fields in access-method control block 85 
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fields, examining control-block displaying (continued) 
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fields in access-method control block 85 
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fields in request parameter list 92 
FIELDS operand, in SHOWCB macro 

fields in access-method control block 76 

fields in exit list 80 

fields in request parameter list 83 
FKS option, in OPTCD operand 56 
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in FIELDS operand 78 
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FTNCD option 

in FIELDS operand 83 
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examples 62,65,70 
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return codes from 42 

used to code a reentrant program 1 59, 1 64 

used to generate 

access method control block 57 
exit list 63 

request parameter list 65 
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example 164 
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ICI option, in MACRF operand 49 
index upgrade 20 
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I/O buffer 
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examples 47 
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relation to processing program work area 56 
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index I/O buffers 46,49 
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interpreting ISAM requests 130 
IO operand, in TESTCB macro 93 
ISAM (indexed-sequential access method) 

(see also indexed-sequential data set and ISAM interface) 

data set, converted to a key-sequenced data set 134 
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ISAM interface 
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processing with 1 30 

purpose 27 
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SYNAD, registers when routine is specified by DCB 132 

use of AMP parameter 1 37 
italics, in notational conventions 4 



JCL (job control language) 

AMP DD parameter 3 1 

converting from ISAM to VSAM 135 
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retrieval 22 
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for deletion 24 
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in MODCB macro 74 

in RPL macro 54 

in TESTCB macro 
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in FIELDS operand 81 
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in FIELDS operand 78 
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Macros, VSAM (continued) 
CLOSE 37 
control block 41 
DLVRP 149 
ENDREQ 127 
ERASE 119 
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used to generate an exit list 63 
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MODCB 
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method of indicating the end of a data set 37 
MF operand, in GENCB, MODCB, SHOWCB, and TESTCB 

macros 1 59 
MLEN operand 
in ACB macro 49 
in FIELDS operand 77 
in GENCB macro 60 
in MODCB macro 71 
in TESTCB macro 86 



MODCB macro 

examples 72,73,74 

execute form 162 

generate form 162 

list form 162 

operand notation for 169 

return codes from 42 
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in FIELDS operand 78 
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TESTCB macros 167 
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NSP option, in OPTCD operand 56 
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NSSS operand 

in FIELDS operand 78 
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in FIELDS operand 78 

in TESTCB macro 86 
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in FIELDS operand 83 
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OBJECT operand 

in SHOWCB macro 75 

in TESTCB macro 87 
OFLAGS operand, in TESTCB macro 88 
OLD, subparameter in JCL 30 
OPEN (in OFLAGS operand in TESTCB macro) 88 
OPEN macro 

connecting program to data 33 

error return codes from 36 

example 35 

ISAM interface 130,139 
OPEN/CLOSE/TCLOSE message area 

in ACB macro 49 

in FIELDS operand 77 

in GENCB macro 60 

in MODCB macro 71 

in TESTCB macro 86 
OPENOBJ operand, in TESTCB macro 88 
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TESTCB macros 167 
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in MODCB macro 74 
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in TESTCB macro 93 
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OPTCD subparameter, in AMP parameter 32 
options 

exit routines 26 
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parameter list 

exit list 41 
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sharing among macros 164 
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PASSWD operand 
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in FIELDS operand 77 

in GENCB macro 61 

in MODCB macro 71 
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passwords 
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PATH option, in OPENOBJ operand 88 
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ISAM interface 132 

SYN AD exit routine 143 
physical-error function codes 97 
physical-error message 100 
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POINT macro 122 

example 122 
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processing options 21 
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providing exit routines 26 
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program, reentrant 159 
programming languages 129 
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examples 111 
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QISAM (queued indexed-sequential access method) 130 
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random access (see direct access) 
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splits 146 
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example, recording when loading records 1 12 
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in FIELDS operand 83 
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modifying 73 
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return codes 
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reusable data set 16 
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in MODCB macro 71 
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RBA 17 
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SHOWCB, and TESTCB 164 
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entry-sequenced data set 18 
SHOWCAT macro 149 
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generate form 163 
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operand notation for 167 

return codes from 42 
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access-method control block 75 
exit list 80 

request parameter list 82 
SHR subparameter, in JCL 30 
SIS option, in MACRF operand 49 
skip-sequential access 

examples 103,113 
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SKP option 

in MACRF operand 49 

in OPTCD operand 56 
SPAN attribute, in ATRB operand 87 
spanned records 16 
SSWD attribute, in ATRB operand 87 
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STMST operand 
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storing a record 
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keyed 22 

skipping 23 
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string extension, dynamic 45,49 
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STRNO operand 

examples 47 

in ACB macro 49 

in FIELDS operand 77 
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in MODCB macro 71 
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STRNO subparameter, in AMP parameter 33 

ISAM interface 138 
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suspending processing, example 126 
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SYNAD exit routine 
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coding 143 
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example 141 
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with ISAM 139 

withVSAM 33 
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execute form 163 
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